Auto-Translate i18n Files on Pull Requests with GitHub Actions

Keeping translation files in sync is one of the most common pain points in multilingual projects. A developer adds new keys to en.json, opens a PR, and the other 15 locale files are immediately out of date. Someone has to remember to translate them before the next release — and someone usually forgets.

glot-translate-action solves this by hooking into your pull request workflow. When the base language file changes, the action detects new or missing keys, translates them via Glot AI, and either commits the translations directly to the PR branch or posts them as a review comment for human review.

How It Works

1. A developer opens a PR that modifies the base locale file (e.g. en.json).
2. The action compares the base file against every target locale file.
3. Keys that exist in the base but are missing in a target are collected.
4. Missing keys are sent to the Glot AI translation API.
5. Translations are committed to the PR branch or posted as a comment.

Quick Setup

Step 1: Get Your API Key

Go to your Account Settings page on Glot and create an API key in the "API Keys" section. Copy the key — you will only see it once.

Step 2: Add the Secret to Your Repository

In your GitHub repository, go to Settings → Secrets and variables → Actions and create a new secret named GLOT_API_KEY with your API key as the value.

Step 3: Create the Workflow File

Create .github/workflows/glot-translate.yml in your repository:

name: Auto-translate i18n files

on:
  pull_request:
    paths:
      - "i18n/locales/en.json"

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}
          fetch-depth: 0

      - name: Glot Translate
        uses: glot-dev/glot-translate-action@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          api_key: ${{ secrets.GLOT_API_KEY }}
          base_lang: en
          locales_path: i18n/locales
          mode: commit

That's it. Every time a PR touches en.json, missing translations will be generated and committed automatically.

Configuration Options

Comment Mode vs Commit Mode

The mode input controls how translations are delivered:

• commit (default) — Translated files are written and committed directly to the PR branch. This is the fastest path: the PR is ready to merge with all translations included.
• comment — Translations are posted as a PR comment with expandable sections for each language. Useful when you want a human reviewer to verify translations before they enter the codebase.

Target Languages

By default, the action auto-detects target languages from existing files in your locales directory. If i18n/locales/ contains en.json, ja.json, and fr.json, it will translate to Japanese and French.

You can override this with the target_langs input:

with:
  target_langs: "ja,ko,zh-TW,fr,de,es"

AI Model Selection

Choose between gpt-4o-mini (fast and cheap, default) and gpt-4o (higher quality, 3x cost). For most projects, gpt-4o-mini produces excellent translations at a fraction of the cost.

What Gets Translated

The action only translates missing keys — keys that exist in the base language file but don't exist in a target file. It never overwrites existing translations. This means:

• Hand-crafted translations are preserved.
• Only genuinely new content gets AI-translated.
• You can run it repeatedly without duplicating work.

Credit Usage

Translations use your Glot account credits. Each key costs 0.05 credits with gpt-4o-mini (0.15 with gpt-4o). If you add 10 new keys and have 15 target languages, that's 150 translations = 7.5 credits. The action reports credit usage in the commit message or PR comment.

Example Workflow: Comment Mode for Review

If your team prefers to review translations before merging:

name: Translate i18n (review mode)

on:
  pull_request:
    paths:
      - "src/locales/en.json"

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - name: Glot Translate
        uses: glot-dev/glot-translate-action@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          api_key: ${{ secrets.GLOT_API_KEY }}
          base_lang: en
          locales_path: src/locales
          mode: comment
          model: gpt-4o

Troubleshooting

Action skips with "base language file not changed"

The action only runs when the base language file (e.g. en.json) is modified in the PR. Make sure the paths filter in your workflow matches the actual file path.

Permission denied on push

Ensure the workflow has contents: write permission and the checkout step uses ref: ${{ github.head_ref }} so it checks out the PR branch (not a detached HEAD).

Insufficient credits

If the action fails with a 402 error, your account doesn't have enough credits. Visit the Pricing page to top up.

Automated translation in your CI pipeline means locale files stay in sync without manual effort. Developers add content in one language, and the rest follows automatically — no Slack reminders, no forgotten locales, no release-day scrambles.