TransMate

TransMate is a CLI tool for managing translations in multi-language web applications. It automatically detects missing translation keys, fills them, and syncs translation files across multiple languages. TransMate also supports AI-powered translations using OpenAI, providing an efficient workflow for managing translation files in your application.

Features

• Automatic Key Addition: Automatically adds missing translation keys to the default and other language files.

• AI-powered Translations: Supports translation of missing keys using OpenAI's API, with configurable AI translation options.

• Dry Run: Preview changes without modifying translation files.

• Translation File Validation: Validates the file structure to ensure translations are correctly organized.

• Sync External Translations: Syncs translations from external sources and services.

• CLI Commands:

  • transmate add-key : Add a missing translation key to the appropriate language files.

  • transmate translate-all: Automatically fills missing translation keys across all languages.

  • transmate sync-translations: Sync translations from an external source.

Installation

Install TransMate via NPM:

```bashCopyEditnpm install -g transmate

Configuration

The configuration file transmate.config.ts is required to set up TransMate. Below is an example configuration:

``` tsCopyEditimport { TransMateConfig } from 'transmate';
        export const config: TransMateConfig = {
            languages: ['en_US', 'fr_FR'],
            defaultLang: 'en_US',
            localesPath: 'public/locales',
            enableAITranslation: true,
            openAIKey: 'your-openai-api-key',
            fileStructure: 'public/locales/{language}/translation.json',
            externalSource: {
                url: 'https://example.com/translations',
            },
        };

Configuration Options:

• languages: Array of languages to manage.

• defaultLang: Default language for the application.

• localesPath: Path to the translation files.

• enableAITranslation: Enable or disable AI-powered translation.

• openAIKey: OpenAI API key (required if AI translation is enabled).

• fileStructure: Template for the translation file structure (e.g., 'public/locales/{language}/translation.json').

• externalSource: URL for syncing translations from an external source.

Commands

transmate add-key

Adds a missing translation key to the appropriate language files. If the key is not found in the translation files:

• Adds the key with the value equal to the key itself for the default language.

• Adds the key with an empty value for other languages.

• If AI translation is enabled, it will use OpenAI to generate translations for other languages.

Options:

• --dry-run: Preview the changes without modifying the files.

transmate translate-all

Translates all missing keys across all languages. For each missing key:

• Adds it with the key as the value in the default language.

• Adds it with an empty value for other languages, or uses AI translation if enabled.

Options:

• --dry-run: Preview the changes without modifying the files.

transmate sync-translations

Syncs translations from an external source (configured in transmate.config.ts). If the external source URL is missing, an error will be thrown.

```bashCopyEdittransmate sync-translations

Error Handling and Validation

File Structure Validation

Before making any changes, TransMate validates the structure of translation files based on the configured fileStructure. If the structure does not match the expected format, an error will be thrown.

• luaCopyEdit❌ Error: Translation file structure does not match the expected format.

AI Translation Validation

If AI translation is enabled (enableAITranslation: true), TransMate checks if the OpenAI API key is configured (openAIKey). If the key is missing, an error is thrown:

• vbnetCopyEdit❌ Error: AI translation is enabled but openAIKey is missing in config.

External Source Validation

If sync-translations is executed but no external source URL is provided in the config, TransMate will throw an error:

• vbnetCopyEdit❌ Error: External source URL is missing in the config.

Missing Translation Key Handling

If a translation key is missing:

• For the default language, the key will be added with the value equal to the key itself.

• For other languages, the key will be added with an empty value. If AI translation is enabled, the key will be translated using OpenAI.

Example:

```vbnetCopyEditAdded key "hello.world" to en_US: "hello.world"  Added key "hello.world" to fr_FR: ""

Contributing

We welcome contributions! If you have any ideas or find bugs, please submit an issue or pull request.

License

ISC License.