# i18n-openai

> The i18n-openai NPM package simplifies and accelerates the translation of i18n JSON files using the power of OpenAI's language capabilities. With this package, developers can effortlessly bridge the language gap and provide multilingual experiences to use

Latest version **1.1.3** (published 2025-03-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install i18n-openai
pnpm add i18n-openai
yarn add i18n-openai
bun add i18n-openai
```

Provides the command `i18n-openai`.

## Health

**Score 35/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.1.3 |
| Published | 2025-03-03 |
| First published | 2023-08-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 60.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Daniil Poletaev |
| Maintainers | danpoletaev |
| Keywords | openai, i18n, automatic, translation, react, next, json |

## Links

- npm: https://www.npmjs.com/package/i18n-openai
- Repository: https://github.com/danpoletaev/i18n-openai
- Homepage: https://github.com/danpoletaev/i18n-openai#readme
- Issues: https://github.com/danpoletaev/i18n-openai/issues
- Funding: https://github.com/danpoletaev/i18n-openai
- npm.io page: https://npm.io/package/i18n-openai

## Dependencies (5)

- [nyc](https://npm.io/package/nyc.md) ^15.1.0
- [dotenv](https://npm.io/package/dotenv.md) ^16.3.1
- [figlet](https://npm.io/package/figlet.md) ^1.6.0
- [openai](https://npm.io/package/openai.md) ^4.86.1
- [commander](https://npm.io/package/commander.md) ^11.0.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.1.3 (latest) — 2025-03-03
- 1.1.2 — 2023-08-12
- 1.1.1 — 2023-08-12
- 1.1.0 — 2023-08-12
- 1.0.2 — 2023-08-12
- 1.0.1 — 2023-08-08
- 1.0.0 — 2023-08-08
- 0.0.11 — 2023-08-08
- 0.0.10 — 2023-08-08
- 0.0.9 — 2023-08-08
- 0.0.8 — 2023-08-08
- 0.0.7 — 2023-08-08
- 0.0.6 — 2023-08-07
- 0.0.5 — 2023-08-07
- 0.0.4 — 2023-08-07
- … 3 more at https://npm.io/package/i18n-openai/versions

## README

# 🚀 i18n-openai

![](https://github.com/danpoletaev/i18n-openai/blob/master/resources/i18n-openai.gif)


[![npm version](https://badge.fury.io/js/i18n-openai.svg)](https://badge.fury.io/js/i18n-openai)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/danpoletaev/i18n-openai/pulls)
![Github Actions](https://github.com/danpoletaev/i18n-openai/actions/workflows/npm-publish.yml/badge.svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
![Coverage](https://img.shields.io/badge/Coverage-85%25-83A603.svg?prefix=$coverage$)

## Table of contents

- [Getting started](#getting-started)
    - [Installation](#installation)
    - [Create config file](#create-config-file-optional)
    - [Add API key](#add-openaai-api-key-to-env)
    - [Translate](#translate)
- [Arguments](#possible-arguments)
- [Configuration Options](#configuration-options)
- [Custom prompt](#custom-prompt)

## Getting started

### Installation
There is two variants of installing a package. Either install it for a certain project to dev dependencies or install it globally.
#### Installing to dev dependencies:
Install using yarn:
```shell
yarn add i18n-openai -D
```
Install using npm:
```shell
npm i i18n-openai --save-dev
```

### Create config file (optional)

You can add your custom config by creating `i18n-openai.config.js`. If no config file would be provided, default config would be used 👇

```js
module.exports = {
    skipLocales: [], // (optional)
    mainLocale: 'en', // (optional)
    pathToLocalesFolders: 'public/locales', // (optional)
    customPrompt:
    'Return content translated to {0}. Keep all sequences /n. Keep all special characters. Do not return any additional information, return only translated text.', // (optional)
    model: 'gpt-3.5-turbo', // (optional)
}
```
If config file is provided, but some of the variables from config are not provided, then default values would be used.

### OpenaAI API key
In order to use OpenAI translation, the key can be provided in .env file.
```js
OPENAI_API_KEY=<your_api_key>
```

Or export API Key
```shell
export OPENAI_API_KEY=<your_api_key>
npx i18n-openai 
```

Or directy in the cli
```shell
npx i18n-openai -apiKey <your_api_key>
```

### Translate
If you have installed package in dev dependencies, then run:
```shell
npx i18n-openai 
```
:warning: If no arguments are provided. `i18n-openai` will translate all files for all locales, except mainLocale provided in config.

### Possible arguments
#### Locales

Use `-locales` to specify locales for translation. The separator is `,`:
```shell
npx i18n-openai -locales ar,cs,de
npx i18n-openai -locales de
```
#### Files
Use `-files` to specify files for translation(files are being taken from main locale folder). The separator is `,`:
```shell
npx i18n-openai -files firstFile.json,secondFile.json
npx i18n-openai -files test.json
```
#### Model
Use `-model` to specify the model to use for translation':
```shell
npx i18n-openai -model gpt-4o
```
#### To see list of all available arguments in terminal use `-h`
```shell
npx i18n-openai -h
```
#### Arguments can be combined (order of arguments does not matter):
```shell
npx i18n-openai -files firstFile.json,secondFile.json -locales ar,de
```
## Configuration Options

| property                                            | description                                                                                                                                                                                                                                                                                                                                                                                                                          | type                                                                                                                     |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| skipLocales(optional)                                             | Locales which will not be translated(Default: [])                                                                                                                                                                                                                                                                                                                                                                                                             | string[]                                                                                                                   |
| mainLocale (optional)                                   | From what locale translation would be. (Default: en)                                                                                                                                                                                                                                                                                                                      | string                                                                                                   |
| pathToLocalesFolders (optional)                               | Relative path to locales folder (Default: public/locales)                                                                                                                                                                                                                                                                                                                                                                                                    | string                                                                                                                   |
| customPrompt(optional)                                 | [see section custom prompt](#custom-prompt)                                                                                                                                                                                                                                                                                                                                                                                                              | string                                                                                                                   |
| model(optional)                                 | Model to use for translation (Default: gpt-3.5-turbo)                                                                                                                                                                                                                                                                                                                                                                                            | string                                                                                                                   |

## Custom prompt

You can specify your custom prompt to use with OpenAI for translation. Custom prompt should contain `{0}` sequence. Language is being replaced by `{0}` once request to OpenaAI is being made.

Default custom prompt: `Return content translated to {0}. Keep all sequences /n. Keep all special characters. Do not return any additional information, return only translated text.`

## Contribution

All PRs are welcome :)

---
_Source: https://npm.io/package/i18n-openai · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
