Verified translation pull requests

Managed publishing moves approved translations back to GitHub as an exact, verified, catalog-only pull request. It never writes directly to the default branch and generated translations require human review by default.

Before you begin

• The Checks App, repository connection, and trusted caller are healthy.
• The caller shown by the dashboard supports catalog sync and publication operations.
• The repository's polyglot.toml declares catalog paths and a [publish] verification command.
• An owner can install the separate Publisher App on the selected repository.

1. Install the Publisher App

Open Automation → Translation PRs and install the Publisher App on the same selected repository. The Publisher App has contents and pull-request write access, so installation is a separate, explicit decision from Checks. It cannot publish until the customer-run workflow returns a verified catalog-only result.

2. Enable catalog synchronization

Read the disclosure, check the consent box, and chooseEnable sync and continue. The trusted repository workflow then uploads the catalog inventory from the default branch: keys, source strings, existing translations, paths, formats, languages, hashes, and related metadata needed for translation and publication.

Keep the page open. It polls the sync state and advances automatically. Use Sync catalogs now to retry or refresh an outdated snapshot. Revoking consent blocks future catalog uploads.

3. Generate and review

Choose Generate N missing translations. Generated values enter review by default. Structural checks can mark a value as eligible for policy auto-approval, but that is not a semantic-quality guarantee; reviewers remain responsible for context, terminology, tone, and product meaning.

• Approve a correct value as-is.
• Edit and approve a corrected value.
• Reject a value to exclude it from publication.
• Resolve ambiguous source values in their key and screen context.

4. Preview the exact pull request

Review translation PR opens the exact candidate. Confirm the repository and target branch, immutable base commit, languages, string and file counts, verification command, catalog-only paths, and each proposed key/value change. The preview hash binds this exact state.

Check the explicit confirmation and chooseVerify and create pull request. This is intentionally a user action; Polyglot does not silently publish generated translations.

5. Verify and create the PR

1. The trusted workflow checks out the pristine immutable base.
2. It runs the configured verification command on that base.
3. It applies only the reviewed, allowlisted catalog changes.
4. It runs the same verification command on the exact candidate.
5. It reports the manifest, hashes, changed paths, and verification result.
6. Only then can the Publisher App create or update the dedicated branch, commit, and pull request.

During early access, publication pull requests default to draft. No branch or pull request is created when baseline verification fails, candidate verification regresses, a source or base drifts, an unapproved path changes, or repository state conflicts.

6. Merge and automatic resync

Review the pull request and its Polyglot / i18n Check in GitHub, then merge it according to your repository rules. The Publisher webhook marks the run merged and the trusted workflow synchronizes the new default-branch catalog. The dashboard progresses fromMerged · pending sync to Published / up to datewithout a local CLI command or manual refresh.

CLI fallback

If your team does not grant Publisher App write access, materialize only approved translations locally and open a pull request yourself:

polyglot pull --approved-only
git diff -- messages/
git checkout -b translations/update
git add messages/
git commit -m "chore: update translations"

For permission and retention detail, read Security and data.