ai-translator.js

A utility that translates JSON or CSV files using OpenAI's API.

Usage

npx @axeptio/ai-translator "./to/translate/*.json" "./translated/{filename}_{locale}.json"  

You will need Open AI credentials to use this tool. You can get them here.

This project uses dotenv. To set your credentials, create a .env file at the root of the project and add the following:

OPENAI_API_KEY=YOUR_API_KEY
OPENAI_ORGANIZATION_ID=YOUR_ORGANIZATION_ID

If you are using the tool in a CI environment, you can also set the credentials using environment variables. If you use the --apiKey and --organizationId options, they will override the values set in the .env file. Finally, when using the interactive mode, you will be asked to enter your credentials if they can not be found.

Arguments and options

Usage: AI Translator translate [options] <input> <outputPattern>

Takes a file or directory and translates its content

Arguments:
  input                                  Input file or directory
  outputPattern                          Output pattern for the translated files (e.g. {filename}-{locale}.{ext})

Options:
  -f, --format <format>                  Format (csv, json) (default: null)
  -l, --locales <locales>                Locales to translate to (default: null)
  -s, --separator <separator>            Separator for CSV files (default: "auto")
  -e, --encoding <encoding>              Encoding for CSV files (default: "utf8")
  -k, --apiKey <apiKey>                  OpenAI API key (default: null)
  -o, --organizationId <organizationId>  OpenAI Organization ID (default: null)
  -v, --verbose                          Verbose mode (default: false)
  -j, --jobOptions <jobOptions>          Job description file (default: null)
  -h, --help                             display help for command

Interactively

When using the CLI interactively, you will be prompted for the following information:

• Translation context: write in plain english context information to guide the AI (e.g. "This is marketing material for a landing page")
• Writing style: give precise guidelines for the AI to work with.
• Output locales: a list of locales you want to translate to
• Protected fields: a list of fields that should not be translated (e.g. "name", "icon", "slug", etc.)
• Field descriptions: a list of fields that require specific instructions (e.g. "title should not exceed 90 characters", etc.)

When using the CLI interactively, you will be asked if you want to save these presets as a job description. If you do, you will be prompted for a name for the job options and a destination folder.

Job Options

If you are processing the same file multiple times, you can save the job options in a JSON file and use it as a template for future runs. The job options file should respect the JSON schema in the src directory, and look like this:

{
  "format": "json",
  "context": "This is marketing material for a landing page",
  "style": "Formal",
  "locales": ["fr", "de", "es"],
  "protectedFields": ["name", "icon", "slug"]
}

Using the tool programmatically

You can also use the tool programmatically. Here is an example:

// if you are using dotenv
import * as dotenv from "dotenv";
dotenv.config();

const { translate } = require('@axeptio/ai-translator');

const input = {
  "title": "This is a title",
  "description": "This is a description",
  "tags": ["do", "not", "translate"],
  "nested": {
    "title": "This is a nested title",
    "description": "This is a nested description"
  },
  "list":[
    { "firstname": "John", "lastname": "Doe", "role": "CEO" },
    { "firstname": "Jane", "lastname": "Doe", role: "Software Engineer" }
  ],
  "isLive": true
};

const options = {
  context: "This is marketing material for a landing page",
  style: "Formal",
  locales: ["fr", "de", "es"],
  openAIConfigurationParameters: {
    apiKey: process.env.OPENAI_API_KEY,
    organizationId: process.env.OPENAI_ORGANIZATION_ID
  },
  // optional parameters
  protectedFields: ["tags", "list.*.firstname", "list.*.firstname"],
  delayMs: 5000,
  verbose: false,
  temperature: 1,
  model: "gpt-3.5-turbo",
}

const translated = await translate(input, options);

console.info(translated);

Things to fix

• [ ] Recursively Chunk data as sometimes 1st level chunks are too big
• [ ] Add a --dry-run option
• [ ] Mock OpenAI API calls in tests
• [ ] Add tests for translate function
• [ ] Find why npx is not working in the working directory