npm package: @sima-cloud/ai-localize
Description: Zero-config i18n extractor and translator CLI
Latest version: 1.1.13

# AI Translation CLI

Zero-config i18n extraction and translation CLI tool to automate the internationalization process for your JavaScript and TypeScript projects.

[![npm version](https://img.shields.io/npm/v/@sima-cloud/ai-translation-cli.svg)](https://www.npmjs.com/package/@sima-cloud/ai-translation-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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

<a href="https://simacloud.dev/" target="_blank">Visit simacloud.dev</a> to get your credentials. Get started for FREE with 5000 words.

## Installation

```bash
npm i @sima-cloud/ai-localize@latest
```


## Quick Start

1. **Initialize the configuration and GitHub workflow**

```bash
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**

```bash
npx ai-localize extract
```

4. **Translate extracted strings**

```bash
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:

```bash
npx ai-localize insert
```

## Configuration

After running `init`, you'll have an `ai-translation.config.js` file in your project root:

```javascript
// 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.

```bash
npx ai-localize init
```

### `extract`

Scans your source code and extracts text strings into JSON files in the source locale directory.

```bash
npx ai-localize extract
```

### `translate`

Translates extracted strings to all target languages configured in your settings.

```bash
npx ai-localize translate
```

### `usage`

Shows your current Sima API plan, token usage, and request count.

```bash
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](https://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](https://simacloud.dev/) for powering the translations
- [Babel](https://babeljs.io/) for AST parsing
- [Commander.js](https://github.com/tj/commander.js/) for the CLI interface