AI Translation CLI

Zero-config i18n extraction and translation CLI tool to automate the internationalization process for your JavaScript and TypeScript projects.

Features

• 🔍 Automatically extracts strings from JSX/TSX files
• 🌐 Translates content using LLMs
• 🚀 GitHub Actions integration for continuous translation
• ⚙️ Zero configuration by default
• 📊 Plan usage monitoring

Visit simacloud.dev to get your credentials. Get started for FREE with 5000 words.

Installation

npm i @routed/ai-localize@latest

Quick Start

1. Initialize the configuration and GitHub workflow

npx ai-localize init

2. Set up your API credentials

Create a .env file in your project root:

SIMA_API_KEY=your_api_key

3. Extract strings from your source code

npx ai-localize extract

4. Translate extracted strings

npx ai-localize translate

5. Rewrite the translated text in JSON format

Rewrites your source files, replacing raw JSX text with an object that holds every available translation:

npx ai-localize insert

Configuration

After running init, you'll have an ai-translation.config.js file in your project root:

// ai-translation.config.js
module.exports = {
  locale: { 
    source: 'en', 
    targets: ['es', 'fr', 'ru'] 
  },
  paths: { 
    src: 'src/**/*.{js,jsx,ts,tsx}', 
    output: 'i18n/{{locale}}' 
  }
};

Configuration Options

| Option | Description | |--------|-------------| | locale.source | Source language code (e.g., 'en') | | locale.targets | Array of target language codes to translate into | | paths.src | Glob pattern for source files to extract strings from | | paths.output | Output directory pattern for translation files |

Available Commands

init

Generates configuration file and GitHub Actions workflow for continuous translation.

npx ai-localize init

extract

Scans your source code and extracts text strings into JSON files in the source locale directory.

npx ai-localize extract

translate

Translates extracted strings to all target languages configured in your settings.

npx ai-localize translate

usage

Shows your current Sima API plan, token usage, and request count.

npx ai-localize usage

GitHub Actions Integration

The init command creates a GitHub Actions workflow file (.github/workflows/i18n.yml) that:

1. Runs on pull requests and pushes
2. Extracts strings from your source code
3. Translates them to target languages
4. Commits the translation files back to your repository

You need to set SIMA_API_KEY and SIMA_USER_ID as secrets in your GitHub repository.

How It Works

String Extraction

The CLI scans JSX and TSX files for text content within JSX tags and extracts them into individual JSON files in the i18n/en/ directory (or your configured source locale).

Translation Process

The extracted strings are sent to the Sima API for translation into your target languages, and the results are saved in corresponding directories (e.g., i18n/es/ for Spanish).

Environment Variables

| Variable | Description | |----------|-------------| | SIMA_API_KEY | Your Sima API key for authentication |

Supported File Types

• JavaScript (.js)
• TypeScript (.ts)
• JSX (.jsx)
• TSX (.tsx)

Getting API Credentials

To obtain your Sima API credentials:

1. Sign up at simacloud.dev
2. Navigate to your account settings
3. Generate or copy your API key

The user should go to https://simacloud.dev/ to get his credentials and to see a short demo.

LLM provider and supported languages

AI Translation CLI uses Llama-3.3-70B-Versatile from Groq for fast AI inference, ensuring quick and accurate translations across all supported languages.

The tool supports translation between 36 languages: English (en), Chinese Simplified (zh-cn), Spanish (es), Arabic (ar), Portuguese (pt), Indonesian (id), French (fr), Japanese (ja), Russian (ru), German (de), Turkish (tr), Korean (ko), Italian (it), Persian/Farsi (fa), Thai (th), Dutch (nl), Polish (pl), Ukrainian (uk), Vietnamese (vi), Hebrew (he), Greek (el), Czech (cs), Swedish (sv), Hungarian (hu), Finnish (fi), Norwegian (no), Danish (da), Romanian (ro), Bulgarian (bg), Croatian (hr), Slovak (sk), Lithuanian (lt), Latvian (lv), Estonian (et), Slovenian (sl), and Catalan (ca).

You can configure any of these languages as your source language and translate to any combination of the others as target languages in your ai-translation.config.js file.

Troubleshooting

Common Issues

Error: Set SIMA_API_KEY

Make sure you've set this environment variable either in a .env file or directly in your terminal.

Translation not working on GitHub Actions

Ensure that you've added the required secrets to your GitHub repository settings.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• Sima API for powering the translations
• Babel for AST parsing
• Commander.js for the CLI interface