Automate i18n Translation with GitHub Actions

You push code. Tests run automatically. Builds deploy automatically.

But your translations? Still manual. Copy-paste into spreadsheets. Wait for translators. Update JSON files by hand.

There's a better way.

---

The Problem

Every time you add a new feature, you update your English locale file.

Then the manual work begins:

• Extract the new keys and send them to translators
• Wait hours or days for translations to come back
• Manually copy translations into es.json, fr.json, de.json...
• Test each locale file for errors
• Commit and push 10+ files

This manual process wastes developer time. It delays feature releases. And it's error-prone—one typo in a locale file breaks your production app.

For a team shipping features weekly, this translation bottleneck costs hours of engineering time per sprint.

---

The Solution

Automation.

Instead of manually managing translations, let your CI/CD pipeline handle them. When you push changes to en.json, GitHub Actions automatically translates to all target languages and commits the results.

The concept is simple: one workflow file replaces hours of manual work.

No more copy-paste. No more waiting. No more errors.

Quick Example

Here's what the automation looks like:

# .github/workflows/translate.yml
name: Auto-translate

on:
  push:
    branches: [main]
    paths:
      - 'locales/en.json'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Translate locale files
        uses: Shipi18n/shipi18n-github-action@v1
        with:
          api-key: ${{ secrets.SHIPI18N_API_KEY }}
          source-file: 'locales/en.json'
          target-languages: 'es,fr,de,ja,zh'

Push to main. Translations happen automatically. Done.

---

Step-by-Step Guide

Setting this up takes about 5 minutes.

Step 1: Get your API key

Sign up at shipi18n.com and grab your API key from the dashboard.

The free tier includes 1,000 translations per month—plenty for most projects.

Step 2: Add the secret to GitHub

Go to your repository settings:

1. Navigate to Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Name: SHIPI18N_API_KEY
4. Value: Paste your API key
5. Click "Add secret"

Your API key is now securely stored and accessible to workflows.

Step 3: Create the workflow file

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

name: Auto-translate

on:
  push:
    branches: [main]
    paths:
      - 'locales/en.json'  # Only run when source file changes

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # Allow the action to commit files

    steps:
      - uses: actions/checkout@v4

      - name: Translate locale files
        uses: Shipi18n/shipi18n-github-action@v1
        with:
          api-key: ${{ secrets.SHIPI18N_API_KEY }}
          source-file: 'locales/en.json'
          target-languages: 'es,fr,de,ja,zh'
          commit-message: 'chore: update translations [skip ci]'

The [skip ci] tag prevents infinite loops—the translation commit won't trigger the workflow again.

Step 4: Test it

Make a change to your locales/en.json file:

{
  "greeting": "Hello, {{name}}!",
  "new_feature": "Check out our new feature"
}

Commit and push to main. Watch the Actions tab—your workflow runs automatically and commits translated files.

Check your repository. You now have es.json, fr.json, de.json, ja.json, and zh.json with perfect translations.

---

Comparison Table

Here's the before/after:

That's 120+ hours saved per year for a team shipping weekly.

Plus zero errors. Plus instant translations in 100+ languages.

---

Advanced Usage

Pull Request Mode

Want to review translations before merging? Use PR mode:

- name: Translate and create PR
  uses: Shipi18n/shipi18n-github-action@v1
  with:
    api-key: ${{ secrets.SHIPI18N_API_KEY }}
    source-file: 'locales/en.json'
    target-languages: 'es,fr,de'
    create-pr: 'true'
    branch-name: 'translations-update'

The action creates a pull request with translations. Review, approve, merge.

Multiple Locale Files

Translating namespaced locale files? No problem:

- name: Translate common namespace
  uses: Shipi18n/shipi18n-github-action@v1
  with:
    api-key: ${{ secrets.SHIPI18N_API_KEY }}
    source-file: 'locales/en/common.json'
    target-languages: 'es,fr,de'
    output-dir: 'locales'

- name: Translate checkout namespace
  uses: Shipi18n/shipi18n-github-action@v1
  with:
    api-key: ${{ secrets.SHIPI18N_API_KEY }}
    source-file: 'locales/en/checkout.json'
    target-languages: 'es,fr,de'
    output-dir: 'locales'

Each namespace gets its own translation step.

Trigger on Pull Requests

Translate before merging to ensure PRs include translations:

on:
  pull_request:
    paths:
      - 'locales/en.json'

Translations are generated as part of the PR review process.

---

Key Takeaways

Here's what you should remember:

1. Automation saves time — 2-4 hours of manual work becomes 2 minutes of automated workflow. Your team ships faster.

2. Zero errors — Automated translation eliminates typos and missing keys. Your production app stays stable.

3. Scales effortlessly — Adding a new language takes one line of configuration. Manual processes don't scale.

---

Next Steps

Ready to automate your translations?

• Get started free with Shipi18n — 1,000 translations/month on the free tier
• View the GitHub Action on the marketplace for full documentation
• Check out example workflows for different use cases
• Browse our integrations for React, Vue, Next.js, and more

---

Stop wasting time on manual translations.

Try Shipi18n Free →