hgi-translate v1.0.3

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 --save-dev hgi-translate

or globally:

npm install -g hgi-translate

Features

• Automatically detects missing translations in JSON files
• Supports nested translation structures
• Integrates with OpenAI
• Automatically commits changes to the Git repository

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
  translationOptions: {
    openai: {
      model: "gpt-4", // model to use
      temperature: 0.3, // translation accuracy (0.0-1.0)
    },
  },

  // 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:16-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
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

{
  "welcome": "Welcome to our app",
  "logout": "Logout"
}

JavaScript and TypeScript Format ( BETA )

export const en = {
  general: {
    logout: "Log out",
    save: "Save",
    add: "Add",
  },
  errors: {
    notFound: "Page not found",
  },
};

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

License

MIT