Dictionary Translation Tool

A Node.js script that automatically translates JSON dictionary files from English to other languages using OpenAI's ChatGPT API.

Features

• 🌐 Translates JSON dictionary files while preserving structure
• 📁 Recursively processes nested directories
• 🔄 Maintains JSON formatting and technical context
• 🎯 Smart translation (only translates values where it makes sense)
• 📝 Creates organized output directory structure
• 🛡️ JSON validation before translation
• 🎨 Accurate language detection with full language names
• ⚡ Low temperature setting for consistent translations

Prerequisites

• Node.js 16+ (ES modules support required)
• OpenAI API key with GPT access
• JSON dictionary files in English

Installation

1. Clone or download this repository
2. Install dependencies:

   npm install

3. Set up environment configuration:

   npm run setup

4. Edit the .env file and add your OpenAI API key:

   OPENAI_API_KEY=your_actual_api_key_here

Directory Structure

The script expects the following structure by default:

project-root/
├── dictionaries/
│   └── en/                 # Source English dictionaries
│       ├── common.json
│       ├── errors.json
│       └── subfolder/
│           └── more.json
├── translate.js            # This script
├── .env                    # Your API key
└── .env.example

Alternative setup: If your dictionaries are elsewhere, you can:

1. Set the DICTIONARIES_PATH environment variable in your .env file
2. Or pass the path when running the command:

   DICTIONARIES_PATH=/path/to/your/dictionaries/en npm run translate:it

After translation, it will create:

project-root/
├── dictionaries/
│   ├── en/                 # Original English files
│   └── hi/                 # Translated Hindi files (example)
│       ├── common.json
│       ├── errors.json
│       └── subfolder/
│           └── more.json

Usage

Using npm scripts (recommended)

# Translate to Hindi (default)
npm run translate

# Translate to specific languages
npm run translate:es    # Spanish
npm run translate:fr    # French
npm run translate:de    # German
npm run translate:it    # Italian
npm run translate:pt    # Portuguese
npm run translate:hi    # Hindi
npm run translate:ja    # Japanese
npm run translate:ko    # Korean
npm run translate:zh    # Chinese

Direct node execution

# Default (Hindi)
node translate.js

# Specify target language
node translate.js es    # Spanish
node translate.js fr    # French
node translate.js de    # German

Quick Start

# 1. Install dependencies
npm install

# 2. Set up environment
npm run setup

# 3. Edit .env with your OpenAI API key
# OPENAI_API_KEY=your_key_here

# 4. Translate to Spanish
npm run translate:es

# 5. Or translate to any language
npm run translate -- ko  # Korean

Supported Languages

Available Scripts

• npm run translate - Translate to Hindi (default)
• npm run translate:es - Translate to Spanish
• npm run translate:fr - Translate to French
• npm run translate:de - Translate to German
• npm run translate:it - Translate to Italian
• npm run translate:pt - Translate to Portuguese
• npm run translate:hi - Translate to Hindi
• npm run translate:ja - Translate to Japanese
• npm run translate:ko - Translate to Korean
• npm run translate:zh - Translate to Chinese
• npm run setup - Copy .env.example to .env

You can also pass any language code directly:

npm run translate -- ar  # Arabic
npm run translate -- ru  # Russian

How It Works

1. File Discovery: Recursively scans the configured dictionaries directory
2. JSON Validation: Validates each JSON file before processing to prevent errors
3. Smart Translation: Sends each JSON file to ChatGPT with specific instructions to:
   • Use full language names (Italian, Spanish, etc.) for better accuracy
   • Preserve JSON structure and keys
   • Only translate user-facing text values
   • Maintain technical context and placeholders
   • Use consistent translation with low temperature setting
4. Output: Creates translated files in dictionaries/{target-language}/

Example

Input (dictionaries/en/common.json):

{
  "buttons": {
    "save": "Save",
    "cancel": "Cancel",
    "submit": "Submit"
  },
  "messages": {
    "welcome": "Welcome to our application",
    "error": "An error occurred"
  }
}

Output (dictionaries/es/common.json):

{
  "buttons": {
    "save": "Guardar",
    "cancel": "Cancelar",
    "submit": "Enviar"
  },
  "messages": {
    "welcome": "Bienvenido a nuestra aplicación",
    "error": "Ocurrió un error"
  }
}

Configuration

OpenAI Model

The script uses gpt-3.5-turbo by default. You can modify this in the code:

model: 'gpt-4' // or 'gpt-3.5-turbo'

Temperature

Set to 0.3 for consistent translations. Lower values (0.0-0.2) give more deterministic results.

Root Directory

Change the ROOT_DIR constant to point to your dictionary location:

const ROOT_DIR = path.join(__dirname, 'your', 'path', 'to', 'dictionaries', 'en')

Error Handling

• ❌ Files with translation errors are logged but don't stop the process
• ✅ Successfully translated files are confirmed with checkmarks
• 📁 Missing directories are created automatically

Cost Considerations

• Translation costs depend on your OpenAI plan and usage
• JSON files are typically small, so costs should be minimal
• Consider using gpt-3.5-turbo for cost efficiency

Troubleshooting

"No such file or directory" error:

• The script looks for dictionaries in ./dictionaries/en/ by default
• If your dictionaries are elsewhere, set DICTIONARIES_PATH in your .env file:

  DICTIONARIES_PATH=/absolute/path/to/your/dictionaries/en

• Or run with the path directly:

  DICTIONARIES_PATH=/your/path npm run translate:es

• Ensure the directory exists and contains .json files

OpenAI API errors:

• Verify your API key is correct and active
• Check your OpenAI account has sufficient credits
• Ensure you have access to the specified model

JSON parsing errors:

• Ensure source files are valid JSON
• Check for any special characters or encoding issues

Contributing

Feel free to submit issues and enhancement requests!

License

This project is open source and available under the MIT License.