cc-translate

An AI-powered i18n translation tool for JSON language files.

Features

• Translate from one source language to multiple target languages.
• Cache-based incremental translation (only changed keys are translated).
• Concurrency queue with retry support for unstable API calls.
• Real-time progress bars and final success/failure summary.
• Cleaner logs for skipped files (No content to translate is aggregated).

Installation

npm install cc-translate

Quick Start

import path from "path";
import { I18nTranslateAgent } from "cc-translate";

const root = process.cwd();

const agent = new I18nTranslateAgent({
  // Required: OpenAI client options
  openaiClientConfig: {
    apiKey: process.env.OPENAI_API_KEY!,
    // baseURL: "https://api.openai.com/v1",
  },

  // Required
  cacheFileRootPath: path.resolve(root, "./cache"),
  fileRootPath: path.resolve(root, "./locales"),
  languages: ["zh-CN", "ja", "ko"],

  // Optional
  sourceLanguage: "en",
  outputRootPath: path.resolve(root, "./locales"),
  concurrency: 8,
  fineTune: [
    "This is a crypto wallet product",
    "Keep blockchain terms consistent",
  ],
  chatCompletionCreateParams: {
    model: "gpt-4o",
    temperature: 0.2,
  },
});

await agent.translate();

Directory Layout

your-project/
├── locales/
│   └── en/
│       ├── common.json
│       └── auth.json
├── cache/
│   ├── zh-CN/
│   └── ja/
└── scripts/translate.ts

API

I18nTranslateAgent

| Option | Type | Required | Description | | --- | --- | --- | --- | | openaiClientConfig | ClientOptions | Yes | OpenAI SDK client options (e.g. apiKey, baseURL) | | cacheFileRootPath | string | Yes | Cache root directory | | fileRootPath | string | Yes | Source locale root directory | | languages | SupportLanguageType[] | Yes | Target language codes | | sourceLanguage | SupportLanguageType | No | Source language, default en | | outputRootPath | string | No | Output directory, defaults to fileRootPath | | concurrency | number | No | Queue length, default 8 | | fineTune | string[] | No | Extra translation context lines | | chatCompletionCreateParams | Partial<ChatCompletionCreateParams> | No | Extra chat completion params |

Utility Exports

import {
  generateCache,
  deleteBatchCache,
} from "cc-translate";

Log Behavior

During translation, skipped files with no diff/content are not printed one by one. They are aggregated into a single summary line to avoid noisy logs in large projects.

Changelog

See CHANGELOG.md.

License

ISC