Automatic Tool for Filling in Missing Translations in Multilingual Projects

Prerequisites

• Node.js installed
• OpenAI API key - You must have an OPENAI_API_KEY environment variable set

Installation

npm install -g hgi-translate

Features

• Automatically detects missing translations in JSON, JavaScript, and TypeScript files
• Supports nested translation structures
• Integrates with OpenAI's API for translation
• Allows providing context for specific keys (using a __context suffix) to improve translation accuracy
• Uses a local cache (.hgi-translate-cache.json) to avoid re-translating unchanged keys, speeding up subsequent runs and allowing manual corrections to persist.
• Automatically commits changes to the Git repository (optional)

Configuration

Create a hgi-translate.config.js file in the root directory of your project:

module.exports = {
  // Base (source) language
  defaultLanguage: "en",

  // List of target languages
  targetLanguages: ["pl", "de", "fr", "es"],

  // Path to the translation directory
  translationsDir: "./src/i18n",

  // Translation options ( safe values compromising speed, token usage and reducing hallucinations )
  translationOptions: {
    batchSize: 150,
    openai: {
      model: "gpt-4.1-nano-2025-04-14", // model to use
      temperature: 0.3, // translation accuracy (0.0-1.0)
      translationContext:
        "This is a technical web application for healthcare professionals with formal tone.",
    },
  },

  // Git options
  git: {
    commitMessage: "chore(hgi-translate): update missing translations",
  },
};

Usage

Basic Usage

# Set your OpenAI API key
export OPENAI_API_KEY=your-api-key  # On Unix/Mac
set OPENAI_API_KEY=your-api-key     # On Windows Command Prompt
$env:OPENAI_API_KEY="your-api-key"  # On Windows PowerShell

# Run the tool
npx hgi-translate

In a Docker-Based Project

You can use hgi-translate in a Docker project in several ways:

1. As Part of the Docker Build Process

In your Dockerfile, add a step that runs hgi-translate before building the application:

FROM node:18-alpine AS builder

WORKDIR /app

# Copy project files
COPY package*.json ./
RUN npm install

# Copy remaining files
COPY . .

# Run hgi-translate before building
RUN npx hgi-translate

# Build the application
RUN npm run build

# Production container
FROM nginx:alpine
COPY --from=builder /app/build /usr/share/nginx/html

2. As a Developer Tool

You can use hgi-translate locally during development and commit the updated translation files to the repository:

npx hgi-translate
git add src/i18n
git commit -m "Update translations"
git push

Then, your CI/CD process will build the Docker image with already updated translations.

As a CLI Tool

# Basic usage (looks for ./hgi-translate.config.js by default)
npx hgi-translate

# With a custom config file path
npx hgi-translate --config ./config/translator.config.js

# Dry run (no actual changes)
npx hgi-translate --dry-run

# Detailed logs
npx hgi-translate --verbose

# Commit and push changes to default branch
npx hgi-translate --push

# Commit and push changes to specified branch
npx hgi-translate --push [branch]

3. In GitHub Actions

Create a workflow file .github/workflows/translations.yml:

name: Update Translations

on:
  push:
    branches: [main]
  # Or manually trigger workflow
  workflow_dispatch:

jobs:
  update-translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v3
        with:
          node-version: "18"

      - name: Configure Git
        run: |
          git config --global user.name 'GitHub Actions Bot'
          git config --global user.email 'github-actions[bot]@users.noreply.github.com'

      - name: Install hgi-translate
        run: npm install -g hgi-translate

      - name: Update translations
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: hgi-translate --verbose --push

Make sure to add your OPENAI_API_KEY to your repository secrets in GitHub:

1. Go to your repository settings
2. Navigate to Secrets and variables > Actions
3. Click "New repository secret"
4. Add OPENAI_API_KEY with your API key

Passing Environment Variables

If using Docker, you can pass API keys as environment variables:

docker build --build-arg OPENAI_API_KEY=your-api-key .

Or in docker-compose.yml:

services:
  app:
    build: .
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}

And in the Dockerfile:

ARG OPENAI_API_KEY
ENV OPENAI_API_KEY=${OPENAI_API_KEY}

Translation File Structure

hgi-translate supports multiple file formats for translations:

JSON Format

Keys ending with __context provide additional context to the AI for the corresponding base key (e.g., logout__context provides context for logout).

{
  "welcome": "Welcome to our app",
  "logout": "Logout",
  "logout__context": "This is translation for logout button."
}

JavaScript and TypeScript Format ( BETA )

Note: This format is stable, but the internal handling might be refined in future versions.

// file: en.ts
export const en = {
  general: {
    logout: "Log out",
    save: "Save",
    add: "Add",
  },
};

// file: en.errors.ts
export const en = {
  notFound: "Page not found",
  serverError: "Internal server error",
};

The tool supports splitting translations across multiple files. For example:

• en.ts - Main translation file
• en.errors.ts - Error messages
• en.forms.ts - Form-related translations

This allows for better organization of large translation sets. The tool will:

• Automatically detect all translation files in the specified directory
• Maintain the same file structure for all target languages
• Preserve the separation of concerns when translating

All formats support nested structures. The tool will automatically detect the file format based on the extension and handle the exports appropriately.

License

MIT