Validate translations in GitHub Actions

Use hyperlocalise/hyperlocalise@v1 with check: check to validate committed translations in pull requests. The action reports missing messages, placeholder errors, and other findings, then fails according to your severity threshold. It does not generate or repair translations.

Choose the check you need

Mode	Question it answers	Scope
`check: check`	Are the current translation files valid and complete?	All configured files by default
`check: check` with `github-diff: true`	Do changed translation keys have issues?	Supported keys in the pull request diff
`check: drift`	Does translation planning find pending work?	The `run --dry-run` plan and reported prune candidates

Use full validation as your baseline. Drift is based on planning and lockfile state; it does not replace validation of the target contents.

Before you start

Commit i18n.yml, source files, and reviewed target files to your repository. Commit .hyperlocalise.lock.json too if you use incremental generation or drift checks. See the quickstart. The examples use GitHub-hosted Ubuntu runners. They need no translation-provider API key because they validate local files without calling a model. Translation and automated repair belong in a separate workflow with provider credentials.

1. Add full validation to pull requests

Create .github/workflows/localization.yml in your app repository:

name: Localization

on:
    pull_request:

permissions:
    contents: read

jobs:
    translations:
        name: Validate translations
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - name: Check translation files
              uses: hyperlocalise/hyperlocalise@v1
              with:
                  check: check
                  config-path: i18n.yml
                  fail-on-findings: true
                  severity-threshold: error
                  github-annotations: true
                  upload-artifact: true

This example fails on errors while keeping warnings visible. Remove severity-threshold: error to use the default threshold, which fails on both warnings and errors. For example, a brand name that matches the source can produce a same_as_source warning. The action installs the CLI. @v1 selects the action release line, while hyperlocalise-version selects the CLI version and defaults to latest. You can pin an exact CLI release or set hyperlocalise-version: config when i18n.yml contains a CLI version pin.

2. Read and reproduce a failure

A missing target key produces a not_localized error. A missing target file produces missing_target_file. Invalid translated ICU structures can produce icu_shape_mismatch. Inspect the job summary and inline annotations where source locations are available. Download check-report.json and check-summary.txt from the uploaded artifact for details. Reproduce the error-level gate locally:

hyperlocalise check --quiet

To see warnings as well:

hyperlocalise check

Fix the relevant target file, or generate missing translations locally, then commit the reviewed result. Use the ICU troubleshooting guide for structural errors. To block merging on this job, select its status check in your repository’s branch protection or ruleset after it has run. Adding a workflow alone does not require that check for merging. See GitHub protected branches.

Check only changed keys

For repositories with existing findings, you can scope a pull request check to changed translation keys. Replace the baseline workflow with:

name: Localization changed keys

on:
    pull_request:

permissions:
    contents: read
    pull-requests: read

jobs:
    translations:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - uses: hyperlocalise/hyperlocalise@v1
              with:
                  check: check
                  config-path: i18n.yml
                  github-diff: true
                  fail-on-findings: true
                  severity-threshold: error

The action uses the GitHub token to fetch the PR diff and passes it to check --diff-stdin. The additional permission allows reading that diff. See GitHub workflow permissions.

Changed-key mode supports .json, .jsonc, and .arb. It ignores unsupported file types, skips files without identifiable changed keys, and omits file-level and document-level checks. Keep full validation for missing files, Markdown/MDX, and other formats. This mode requires a pull request event.

If source IDs include extract --prefix-id filename prefixes but your targets use pack --prefix-id, add prefix-id: true to the action inputs.

Detect pending translation work

Use drift mode to inspect the translation plan:

name: Localization drift

on:
    pull_request:

permissions:
    contents: read

jobs:
    drift:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - uses: hyperlocalise/hyperlocalise@v1
              with:
                  check: drift
                  config-path: i18n.yml
                  fail-on-drift: true
                  upload-artifact: true

The action runs hyperlocalise run --dry-run. It considers executable tasks or prune candidates reported by the plan to be drift. It uploads drift-report.json and drift-summary.txt. Command failures still fail the action when fail-on-drift is false. Use the changed-string workflow to update translations and checkpoint state. A clean drift result is not a guarantee that every target message is valid.

Action inputs

Input	Default	Purpose
`check`	`drift`	Select `drift` or `check`
`config-path`	`i18n.yml`	Configuration path relative to the working directory
`working-directory`	`.`	Directory where the CLI runs
`hyperlocalise-version`	`latest`	CLI release, or `config` for a configuration pin
`fail-on-findings`	`true`	Fail validation on findings at the selected threshold
`severity-threshold`	`warning`	Fail on `warning` and error findings, or only `error` findings
`github-diff`	`false`	Validate changed keys in a PR; `check` mode only
`prefix-id`	`false`	Compare prefixed source IDs with packed target IDs; `check` mode only
`github-annotations`	`true`	Emit inline annotations when locations are available
`upload-artifact`	`true`	Upload JSON reports and text summaries
`summary-format`	`compact`	Use `compact` or `detailed` job summaries
`summary-limit`	`20`	Maximum findings shown in the job summary
`fail-on-drift`	`true`	Fail when drift mode finds pending work

For a monorepo, set working-directory: apps/web and keep config-path: i18n.yml if the configuration lives at apps/web/i18n.yml.

Next steps

Check command reference lists findings and local flags.
CI automation covers installation and sync patterns.
React Intl tutorial covers extraction before validation.

​Choose the check you need

​Before you start

​1. Add full validation to pull requests

​2. Read and reproduce a failure

​Check only changed keys

​Detect pending translation work

​Action inputs

​Next steps

Choose the check you need

Before you start

1. Add full validation to pull requests

2. Read and reproduce a failure

Check only changed keys

Detect pending translation work

Action inputs

Next steps