GitHub Action Integration

Keep translations in sync automatically on every push or pull request.

View on GitHub View on GitHub Marketplace

Features

Commits translations directly or opens a pull request

Incremental — only changed keys are translated

Local verification of placeholders, keys and length

Skip keys or paths with glob patterns

Anthropic or OpenAI with your own key from repo secrets

Prerequisites

1.A GitHub repository with locale files
2.An LLM API key stored as a repository secret

Installation

# .github/workflows/translate.yml
uses: Shipi18n/shipi18n-github-action@v2

Configuration

Add your key under Settings → Secrets and variables → Actions as ANTHROPIC_API_KEY, then reference it in the workflow. The action needs contents: write to commit, or pull-requests: write to open a PR.

Usage

uses: Shipi18n/shipi18n-github-action@v2

Examples

Translate on every push to main

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

permissions:
  contents: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Shipi18n/shipi18n-github-action@v2
        with:
          source-file: locales/en.json
          target-languages: es,fr,de
          provider: anthropic
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Open a pull request instead of committing

      - uses: Shipi18n/shipi18n-github-action@v2
        with:
          source-file: locales/en.json
          target-languages: es,fr
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          create-pr: 'true'
          branch-name: shipi18n-translations

Leave legal copy in English

      - uses: Shipi18n/shipi18n-github-action@v2
        with:
          source-file: locales/en.json
          target-languages: es,fr
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          skip-keys: 'legal.*,brand.name'

Best Practices

Filter the trigger on your source locale path so the job only runs when the strings actually change.
Use create-pr on shared repos — a review step on generated copy is cheap insurance.
Pin to @v2; the major tag moves with patch releases but never across breaking changes.
Skip brand names and legal text rather than translating and reverting them.

Troubleshooting

Permission denied when committing

Add permissions: contents: write to the job (or pull-requests: write when using create-pr).

The action ran but changed nothing

Incremental mode is on by default, so unchanged keys are skipped. Set incremental: false to force a full re-translation.

Missing API key

Pass api-key from a repository secret, or set ANTHROPIC_API_KEY in the job env. The action has no key of its own.

Need help? Read the docs

View on GitHub