Skip to content
Locize
LoginRegister

GitHub Actions

Locize provides three official GitHub Actions for integrating translations into your CI/CD pipeline.

Translate Action

Go from your source keys to AI-translated, CDN-delivered locale files in a single CI step. It wraps the i18next-cli localize flow: it extracts new and changed keys, syncs them to Locize, triggers AI auto-translation, and downloads the results. Instrumentation (rewriting your source to add t() calls) is always skipped in CI, so your source files are never modified.

- uses: locize/translate@v1
  with:
    project-id: ${{ secrets.LOCIZE_PROJECTID }}
    api-key: ${{ secrets.LOCIZE_API_KEY }}

This action expects an i18next.config.{ts,js} in your repository (run npx i18next-cli init once and commit it). A brand new free project can auto-translate a limited starter amount out of the box; for continuous translation, subscribe or bring your own AI/MT key.

Looking for the why and the free story (how "free" works, and an honest comparison to the lingo.dev Action and ai-i18n)? See Free CI translation for i18next.

Example: translate and commit

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: locize/translate@v1
        with:
          project-id: ${{ secrets.LOCIZE_PROJECTID }}
          api-key: ${{ secrets.LOCIZE_API_KEY }}
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'chore(i18n): update translations'

Example: sync only (already extracted)

If your locale files are already extracted, set command: sync to skip extraction and only reconcile the existing files with Locize:

- uses: locize/translate@v1
  with:
    command: sync
    project-id: ${{ secrets.LOCIZE_PROJECTID }}
    api-key: ${{ secrets.LOCIZE_API_KEY }}

See the Translate Action documentation for all options (cdn-type, update-values, dry-run, cli-version, etc.).

Download Action

Fetch the latest published translations from Locize during your build.

- uses: locize/download@v4
  with:
    project-id: ${{ secrets.LOCIZE_PROJECTID }}

Note: The action downloads translations into the CI/CD container. To store them back in your repository, add a commit/push step (e.g., GitHub Commit Push Action).

Example: download and commit

jobs:
  my_job:
    runs-on: ubuntu-latest
    name: download and push
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Download translations
        uses: locize/download@v4
        with:
          project-id: ${{ secrets.LOCIZE_PROJECTID }}
      - name: Commit & Push changes
        uses: actions-js/push@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

See the Download Action documentation for all options (format, language filtering, path masks, CDN type, etc.).

Sync Action

Bidirectional sync between your local translation files and Locize. Pushes new keys, removes deleted keys, and can trigger automatic AI/MT translation (the project-side workflow is enabled by default for new projects).

- uses: locize/sync@v2
  with:
    api-key: ${{ secrets.LOCIZE_API_KEY }}
    project-id: ${{ secrets.LOCIZE_PROJECTID }}
    path: locales

Example: sync with auto-translate

- uses: locize/sync@v2
  with:
    api-key: ${{ secrets.LOCIZE_API_KEY }}
    project-id: ${{ secrets.LOCIZE_PROJECTID }}
    path: locales
    auto-translate: true

When auto-translate is enabled, any new or updated keys synced to the reference language will be automatically translated into all target languages using the project's configured AI or MT provider.

Example: sync, then publish

steps:
  - uses: actions/checkout@v6

  - uses: locize/sync@v2
    with:
      api-key: ${{ secrets.LOCIZE_API_KEY }}
      project-id: ${{ secrets.LOCIZE_PROJECTID }}
      path: locales
      auto-translate: true

  - run: npx locize-cli publish-version
    env:
      LOCIZE_API_KEY: ${{ secrets.LOCIZE_API_KEY }}
      LOCIZE_PROJECTID: ${{ secrets.LOCIZE_PROJECTID }}

See the Sync Action documentation for all options (branch targeting, format selection, dry run, etc.).

Best Practices

  • Store your Locize project ID and API key as GitHub secrets.
  • Use translate to go from source keys to AI-translated, CDN-delivered locales in one step (the quickest way to wire up CI translation for an i18next project).
  • Use download for build-time bundling (SSG, SSR) to fetch published translations into your build.
  • Use sync for keeping your local translation files and Locize in sync: push new keys, pull translations, trigger auto-translation.
  • Combine sync + publish for a complete translation CI/CD pipeline.