npm package: @i18nai/cli
Description: > [!WARNING]   > This library is currently in development and not all features are available.
Latest version: 0.0.1-dev.0.0.12

# @i18nai/cli

> [!WARNING]  
> This library is currently in development and not all features are available.


Command-line interface for managing internationalization in your projects using the i18n.ai platform.

## Installation

```bash
# Global installation (recommended)
npm install -g @i18nai/cli

# Local installation
npm install --save-dev @i18nai/cli
```

## Features

- 🚀 Quick project initialization
- 🔄 Automated translation generation
- 📁 Structured locale file management
- 🔑 Integration with i18n.ai API
- 🎯 Support for nested translation keys
- 🔒 Preserves existing translations
- ⚡️ Fast and efficient processing

## Commands

### Initialize Project

Sets up the i18n configuration and creates initial locale files in your project.

```bash
i18nai init
```

This command will:
1. Create an `i18n` directory in your project root
2. Generate a `config.json` file with default settings
3. Create locale files for English, Spanish, and French
4. Set up sample translations to get you started

Generated project structure:
```
your-project/
└── i18n/
    ├── config.json
    └── locales/
        ├── en.json
        ├── es.json
        └── fr.json
```

Default configuration (`config.json`):
```json
{
  "name": "your-app-name",
  "defaultLang": "en",
  "supportedLangs": ["en", "es", "fr"]
}
```

### Translate Content

Automatically translates your content to all supported languages using the i18n.ai API.

```bash
# Basic usage
i18nai translate

# Using a custom API host
i18nai translate --host=http://localhost:3000
# or
i18nai translate -h=http://localhost:3000
```

This command:
- Reads your English translations
- Uses the i18n.ai API (or specified host) to translate to configured languages
- Updates locale files with new translations
- Preserves existing translations
- Handles nested translation structures

#### Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--host` | `-h` | API host URL | `https://i18n.ai` |

## Configuration

### Project Configuration

The `i18n/config.json` file supports the following options:

```json
{
  "name": "your-app-name",     // Project name
  "defaultLang": "en",         // Source language
  "supportedLangs": [          // Target languages
    "en",
    "es",
    "fr"
  ]
}
```

### API Configuration

To use the translation features:

1. Sign up at [i18n.ai](https://i18n.ai)
2. Get your API key from the dashboard
3. Set up your API key:
   ```bash
   export I18NAI_API_KEY=your_api_key
   ```

## Translation File Format

Each locale file (`locales/*.json`) follows this structure:

```json
{
  "simple": "Simple translation",
  "nested": {
    "key": "Nested translation",
    "with_params": "Hello, {{name}}!"
  },
  "deeply.nested.key": "Deeply nested translation"
}
```

## Usage with CI/CD

For automated translation in CI/CD pipelines:

```bash
# Set API key in CI environment
export I18NAI_API_KEY=your_api_key

# Run translation
i18nai translate
```

## Error Handling

The CLI provides clear error messages for common issues:

- Missing API key
- Invalid configuration
- Network errors
- Invalid translation files

Example error handling:
```bash
# Check if API key is set
if [ -z "$I18NAI_API_KEY" ]; then
  echo "Error: I18NAI_API_KEY is not set"
  exit 1
fi

# Run translation with error handling
i18nai translate || {
  echo "Translation failed"
  exit 1
}
```

## Dependencies

- Node.js >= 14
- [@i18nai/sdk](https://www.npmjs.com/package/@i18nai/sdk): Core SDK package
- Internet connection for translation features

## License

MIT