GitHub Actions

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

Download Action

Fetch the latest published translations from Locize during your build.

• Repository: locize/download

- uses: locize/download@v2
  with:
    project-id: ${{ secrets.LOCIZE_PROJECT_ID }}

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@v2
        with:
          project-id: ${{ secrets.LOCIZE_PROJECT_ID }}
      - 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 optionally triggers automatic AI/MT translation.

• Repository: locize/sync

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

Example: sync with auto-translate

- uses: locize/sync@v1
  with:
    api-key: ${{ secrets.LOCIZE_API_KEY }}
    project-id: ${{ secrets.LOCIZE_PROJECT_ID }}
    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@v1
    with:
      api-key: ${{ secrets.LOCIZE_API_KEY }}
      project-id: ${{ secrets.LOCIZE_PROJECT_ID }}
      path: locales
      auto-translate: true

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

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 download for build-time bundling (SSG, SSR) — 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.