How to prevent untranslated UI from reaching production with GitHub

The naive localization gate is simple: scan the repository and fail if any untranslated string exists. It's also the fastest way to make a team disable the check.

Real codebases already have localization debt. A useful pull-request check answers a narrower question first: did this change make things worse? Answer that well and you can adopt the check today — and get stricter whenever you're ready.

Start with a differential check

A differential check compares your PR against its base and sorts findings into three buckets:

• New — introduced by this change
• Existing — inherited debt
• Resolved — fixed by this change

Existing debt stays visible, but it isn't the author's problem on every unrelated PR. New strings are.

With Polyglot, the open GitHub Action runs this on any plan, from a workflow in your repo:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- uses: polyglot-i18n/[email protected]
  with:
    check-mode: differential

That, plus a committed polyglot.toml (run polyglot init --local once), is the whole setup. No API key required — the Action runs in guest mode.

By default, the check uses the no-new policy: existing debt is reported but allowed, and the job fails when a PR adds a new finding. A failed job only blocks merging once you make it a required check in GitHub.

Turn on blocking deliberately

Don't make an unfamiliar signal a required check on day one. A rollout that sticks looks like this:

1. Run it informational for a week or two. Set the policy in polyglot.toml:

   [ci]
   preset = "informational"
   

2. Check for false positives and configuration gaps.

3. Look at your baseline — that's your existing debt, counted.

4. Agree on who owns new findings.

5. Switch back to no-new (the default), then make the check required in GitHub.

Nobody's merge gets blocked until you decide it should.

Let Polyglot open the translation PR

Polyglot Automation — in early access for Team and Scale — picks up where the check leaves off. When new strings land, it keeps your catalogs in sync, generates translations, and holds them for human review. Once someone approves, Polyglot verifies the change against a pristine base — your configured verification command has to pass on both — and the Publisher App opens a separate catalog-only pull request. Your team merges it, and Polyglot resyncs from your default branch.

The open Action doesn't do this part. It checks PRs; it doesn't generate translations or open translation PRs.

A few design decisions worth knowing before you install anything:

• Two separate GitHub Apps. The Checks App can't write repository contents at all. The Publisher App — a separate, optional install — can only push verified catalog branches and open pull requests.
• No long-lived secrets. The managed workflow authenticates with GitHub OIDC and gets a short-lived credential scoped to a single run.
• Never straight to main. Translations arrive as a PR — a draft by default during early access — and your branch protections and code review still decide what merges.
• Blocking is opt-in and gated. Managed Checks start informational. Policies that block a merge are in early access, and they only block once Polyglot verifies the Check is required in your branch rules.

Keep a human in the loop

Generated translations aren't approved changes. Automatic approval is off: someone sees the source string, the context, and the exact diff before anything ships. If verification fails on the candidate, the PR doesn't open.

That's the whole idea. The check stops regressions where they start, and translations ship the way the rest of your code does — as a pull request someone reviewed.

Add the open Action today. The rest is there when your team wants it.