TasHelix Translation Generator

A powerful CLI tool for managing translations across multiple languages using AI. Supports any project structure and provides flexible configuration options.

🚀 Features

• AI-Powered Translations: Uses OpenAI models for accurate translations
• Flexible Directory Structure: Works with any project layout
• Sync Command: Automatically sync translations from English to all languages
• Incremental Updates: Only translates missing keys, preserves existing translations
• Configurable AI Models: Choose between gpt-4o, gpt-4o-mini, or gpt-3.5-turbo
• Smart Configuration: Auto-saves settings with CLI overrides
• Cross-Platform: Works on Windows, macOS, and Linux
• YAML-Based: Human-readable translation files

📦 Installation

# Install globally
npm install -g @tashelix/translation-generator

# Or use with npx (no installation required)
npx @tashelix/translation-generator --help

🔧 Quick Start

1. Initialize your project

# Set up configuration (optional - will use defaults if skipped)
translations init --dir ./src/i18n --model gpt-4o

# This creates a translation.config.json file:
# {
#   "translationDir": "./src/i18n",
#   "model": "gpt-4o"
# }

2. Add your first translation key

# Add a new translation key
translations key add WELCOME "Welcome to our app" "Main greeting message"

# This creates/updates:
# - translations.yaml (with key descriptions)
# - en.yaml (with English text)
# - Generates translations for all configured languages

3. Add more languages

# Add new languages
translations lang add fr  # French
translations lang add es  # Spanish
translations lang add de  # German

4. Keep translations in sync

# When you add/modify translations in en.yaml, sync to all languages
translations sync

# This automatically:
# - Updates translations.yaml with new keys
# - Generates missing translations in all language files
# - Preserves existing translations

📚 Usage

Global Options

All commands support these optional global options:

• --dir <path>: Specify translation directory
• --model <model>: Specify AI model (gpt-4o, gpt-3.5-turbo, etc.)
• --verbose: Show detailed output
• --quiet: Minimal output

Commands

init - Initialize Configuration

# Interactive setup
translations init

# With options
translations init --dir ./locales --model gpt-3.5-turbo

key - Manage Translation Keys

# Add a new key
translations key add BUTTON_SAVE "Save" "Save button text"

# Add with custom settings
translations --model gpt-4o key add MENU_HOME "Home" "Navigation menu item"

# Delete a key
translations key delete OLD_BUTTON

lang - Manage Languages

# Add a new language
translations lang add fr

# Add multiple languages (run command multiple times)
translations lang add de
translations lang add es
translations lang add it

sync - Sync Translations from English

The sync command reads your en.yaml file and automatically:

1. Updates translations.yaml with any missing keys (with empty descriptions)
2. Generates translations for missing keys in all other language files
3. Preserves existing translations (non-destructive)

# Basic sync - reads en.yaml and updates all language files
translations sync

# Sync with verbose output to see what's happening
translations sync --verbose

# Sync with specific directory and model
translations sync --dir ./locales --model gpt-3.5-turbo

Typical workflow:

# 1. Edit your en.yaml file directly or use key commands
translations key add NEW_FEATURE "New Feature" "A brand new feature"

# 2. Sync to propagate changes to all languages
translations sync

# The sync command will:
# - Add NEW_FEATURE to translations.yaml (if not exists)
# - Generate translations for NEW_FEATURE in fr.yaml, es.yaml, etc.
# - Skip keys that already exist (preserves human edits)

🔧 Configuration

Configuration File

The tool uses translation.config.json for persistent settings:

{
    "translationDir": "./src/i18n",
    "model": "gpt-4o"
}

Supported AI Models

• gpt-4o (recommended, balanced cost/quality)
• gpt-4o-mini (fastest, lowest cost)
• gpt-3.5-turbo (legacy, good for simple translations)### Directory Structure

The tool creates and maintains this structure:

your-project/
├── translation.config.json
├── src/i18n/                    # or your custom directory
│   ├── translations.yaml        # key descriptions
│   ├── en.yaml                 # English translations
│   ├── fr.yaml                 # French translations
│   └── es.yaml                 # Spanish translations

File Formats

translations.yaml - Key descriptions for AI context:

WELCOME: "Main greeting message shown on app launch"
BUTTON_SAVE: "Text for the primary save button"
ERROR_NETWORK: "Error message when network request fails"

en.yaml - English source text:

WELCOME: "Welcome to our app"
BUTTON_SAVE: "Save"
ERROR_NETWORK: "Network connection failed"

fr.yaml - French translations:

WELCOME:
    value: "Bienvenue dans notre application"
    source: "ai"
BUTTON_SAVE:
    value: "Enregistrer"
    source: "ai"
ERROR_NETWORK:
    value: "Échec de la connexion réseau"
    source: "ai"

🔐 Environment Variables

# OpenAI API Key (required)
export OPENAI_API_KEY="sk-your-api-key-here"

🧪 Examples

Workflow 1: Command-driven (Recommended for new projects)

# Start fresh
translations init --dir ./src/i18n

# Add keys one by one with AI translation
translations key add WELCOME "Welcome!" "Main greeting"
translations key add BUTTON_SAVE "Save" "Save button"

# Add languages (automatically translates existing keys)
translations lang add fr
translations lang add es

Workflow 2: Sync-driven (Recommended for existing projects)

# Initialize in existing project with en.yaml
translations init --dir ./src/i18n

# Add languages
translations lang add fr
translations lang add es

# Edit en.yaml manually with your translations, then sync
translations sync

Next.js Project

cd my-next-app
translations init --dir ./src/locales
translations key add PAGE_TITLE "Home Page" "Title for the home page"
translations lang add fr
translations lang add es

Vue.js Project

cd my-vue-app
translations init --dir ./src/i18n
translations key add NAVBAR_ABOUT "About" "About page link in navigation"
translations lang add de
translations lang add it

Express.js API

cd my-api
translations init --dir ./locales
translations key add ERROR_VALIDATION "Validation failed" "Generic validation error message"
translations lang add fr
translations lang add es

🐛 Troubleshooting

Common Issues

1. API Key Missing

   export OPENAI_API_KEY="sk-your-key"

2. Permission Errors

   # Make sure directory is writable
   chmod 755 ./src/translations

3. Configuration Issues

   # Check your configuration
   translations init --verbose

4. Sync Command Issues

   # Make sure en.yaml exists before syncing
   ls ./src/i18n/en.yaml
   
   # Use verbose mode to see what's happening
   translations sync --verbose

Debug Mode

# Enable verbose logging for any command
translations --verbose key add DEBUG "Debug" "Debug message"
translations --verbose sync

📝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• � Email Support - Contact us for help, report bugs or request features