Lingui AI Translator

Automatically translate missing Lingui translations using OpenAI (GPT-4.1 model).

Features

• Automatically detects and loads your Lingui configuration
• Finds all missing translations in your message catalogs
• Batch translates missing messages using OpenAI
• Preserves your existing translations and file structure
• Supports dry-run mode to preview translations
• Works with Lingui's JSON format

Installation

npm install lingui-ai-translator
# or
bun add lingui-ai-translator

Prerequisites

1. A OpenAI API key from https://platform.openai.com/
2. An existing Lingui project with a lingui.config.js file
3. Some existing message catalogs with translations

Usage

Command Line

# Set your OpenAI API key
export OPENAI_API_KEY=your-api-key-here

# Translate all missing messages
lingui-ai translate

# Translate specific locales only
lingui-ai translate --locales es fr de

# Dry run to preview translations
lingui-ai translate --dry-run

# Specify custom config path
lingui-ai translate --config ./custom-lingui.config.js

Programmatic API

import { LinguiTranslator } from 'lingui-ai-translator';

const translator = new LinguiTranslator({
  apiKey: process.env.OPENAI_API_KEY,
  rootDir: process.cwd(),
  locales: ['es', 'fr'],
  batchSize: 10,
  dryRun: false,
});

await translator.translate();

Configuration

Create a .env file in your project root:

OPENAI_API_KEY=your-openai-api-key-here

How it works

1. The tool searches for your lingui.config.js file
2. Extracts all translation file paths from the config
3. Loads each translation file and identifies missing translations (empty strings)
4. Sends batches of missing translations to OpenAI for translation
5. Updates the translation files with the AI-generated translations

Supported Lingui Format

The tool works with Lingui's JSON format:

{
  "messageId": {
    "translation": "Translated message",
    "message": "Default message",
    "description": "Comment for translators",
    "origin": [["src/App.js", 3]]
  }
}

CLI Options

• -k, --api-key <key> - OpenAI API key (alternative to env variable)
• -c, --config <path> - Path to Lingui config file
• -r, --root <path> - Root directory of your project
• -l, --locales <locales...> - Specific locales to translate
• -b, --batch-size <size> - Number of translations per batch (default: 10)
• -d, --dry-run - Preview translations without saving

License

MIT