GitHub App

The Translatize GitHub App gives every pull request that changes your source strings its own translation branch and a Translatize check with translation status and quality results. Translations can be committed back to the pull request, and the branch is merged into your base branch when the pull request merges. There is no workflow file to write and no token secret to store.

What you need

• A project on the Professional or Agency plan (see Plans).
• The admin or owner role in the Translatize project.
• Write or admin access to the repository on GitHub, for your own GitHub account. The repository is on github.com.
• JSON locale files, one per language, such as locales/en.json and locales/de.json – nested or flat.

Install and link a repository

1. In the app, open the project, then Project Settings → GitHub (in the Developers group). Only admins and owners see this tab.
2. Under 1. Install the GitHub App, click Install the GitHub App (Install on another account when an installation is already listed). GitHub opens in a new tab.
3. On GitHub, choose your account or organization and the repositories the app may access, and confirm. You can change that list later on GitHub. On an organization, GitHub may send your request to an organization owner instead – once they approve it, click Install the GitHub App again and choose the organization.
4. GitHub sends you back to the project's GitHub tab, which confirms: "The GitHub App is installed on your-account. Pick a repository below to finish."
5. Under 2. Pick a repository, choose the repository and the Base branch – the Translatize branch that pull request branches start from and are merged back into, usually main. Set the options described under Settings and click Link repository.
6. Commit a translatize.config.json to the root of the repository. The tab shows one with your project id filled in, under Add translatize.config.json to the repository, with a Copy button. Pull requests whose branch contains the file are processed from then on.

Linking is tied to your own GitHub account: the repository list shows only repositories it can write to, as GitHub confirmed during the install. Another admin of the project who wants to link a repository goes through Install the GitHub App once with their own GitHub account. If the organization uses single sign-on, sign in to it on GitHub first.

A project links one repository, and a repository can be linked to one project at a time. Once linked, the tab shows the repository with its status – Active, Paused – plan or Paused – needs attention – and, when it is paused, what to do about it.

translatize.config.json

The app reads translatize.config.json from the root of the repository, at the pull request's latest commit – so a change to the file applies to the pull request that makes it. It is the same file the CLI and the GitHub Action read, plus an optional github block that the CLI ignores.

{
  "projectId": "your-project-id",
  "format": "json-nested",
  "files": "locales/{lang}.json",
  "github": {
    "autoTranslate": true,
    "commitTranslations": "on-request",
    "requireComplete": false,
    "syncDefaultBranch": true
  }
}

Every field the file can hold:

The github block. A key you leave out falls back to the setting in the GitHub tab; the defaults below are the tab's own.

A file with every field looks like this – apiUrl and branch are there for the CLI:

{
  "apiUrl": "https://api.translatize.com/v1",
  "projectId": "your-project-id",
  "format": "json-flat",
  "files": "src/i18n/{lang}.json",
  "namespace": "web",
  "branch": "main",
  "github": {
    "sourceLanguage": "en",
    "autoTranslate": true,
    "commitTranslations": "auto",
    "requireComplete": true,
    "syncDefaultBranch": false
  }
}

The source file and each language file are read and written as JSON and nothing else. A file larger than 5 MB is skipped with a note on the check, and the config file itself may be up to 64 KB.

What happens on a pull request

Take pull request #42, which rewords one button and adds another in the source file:

// locales/en.json in pull request #42
{
  "checkout": {
-   "cta": "Buy now",
+   "cta": "Complete purchase",
+   "express": "Pay with one click"
  }
}

When the pull request is opened, gets new commits, is reopened or is marked ready for review – drafts included – the app does this:

1. Compares the source file. It reads the config and the source-language file at the pull request's latest commit and compares the file with the commit the pull request branched off. Strings that changed on the base branch since then don't count as the pull request's. Here: checkout.express is added and checkout.cta is changed.
2. Creates the branch. The first time, it creates the Translatize branch pr-42 from your base branch; later pushes reuse it. If a branch called pr-42 already exists and the app did not create it, the app uses pr-42-2, then pr-42-3, and so on, and leaves the existing branch alone.
3. Adds the strings. The new and changed source strings are written to pr-42 in the source language. Keys removed from the source file are listed on the check but stay in Translatize.
4. Translates them. With AI translation on, the strings that changed since the last push the app processed are translated into every other project language. A changed string gets fresh translations on pr-42; the base branch keeps its old ones until the merge. A push that doesn't touch the source file translates nothing, so it uses no AI characters.
5. Checks quality. The quality checks run on the changed keys, and the project's merge gate says whether it would let pr-42 merge.
6. Reports. The app posts the Translatize check on the pull request's latest commit, and updates it on every later push.

A pull request that adds or changes no source string gets a passing check, "No translation changes", and no branch. Changes to the other language files don't count: the app reads only the source-language file of a pull request.

When someone works on pr-42 in Translatize – a translator fills in a language, a reviewer fixes a string – the check updates on its own. Everyone in the project sees a PR #42 badge next to the branch in the branch lists, which links to the pull request.

When AI translation runs

It is the same AI translation you start in the app, so the project's AI translation settings apply, and it uses the project's monthly AI translation characters. If AI review after AI translation is on under Quality checks, the pull request's translations are reviewed too. It does not run:

• when Translate new strings automatically is off (or autoTranslate is false);
• for pull requests from forks;
• when the project has no language besides the source language.

If another translation job is running in the project, the app waits for it and starts afterwards. If the characters left this month are not enough for the strings, nothing is translated and the check says so in its notes.

Pull requests from forks

A pull request from a fork gets its branch and its check like any other. It is never AI-translated – anyone can open one, and it would spend your project's AI translation characters – and nothing is ever committed to a fork. The check says so. Translate its strings in Translatize; they are merged with the rest when the pull request merges.

The Translatize check

The check is called Translatize. Its Details link opens the pull request's branch in Translatize. The title tells you where things stand:

The summary underneath shows:

• how many keys were added and changed, and the source language;
• a table with Translated and Missing per target language, for the changed keys (any value counts as translated, whatever its review status);
• the QA errors and warnings, with the merge gate mode – or that the gate blocks this merge;
• how many keys the pull request removed;
• a link such as Open pr-42 in Translatize, and below the summary the changed and removed keys and any notes.

The merge gate is set in Project Settings → Quality checks. Its default, Warn, shows QA errors without failing the check; Block makes them fail it. If the gate covers main only and your base branch is another branch, the check says the gate does not apply.

Committing translations back

Translations live on the pull request's Translatize branch. Whether they are also committed to the pull request is your choice:

Sync translations appears on the check when the mode is On request, the pull request comes from a branch of the same repository, it changes source strings, and no translation is running.

The commit is one commit on the pull request's branch, made by the app, with the message chore(i18n): sync translations from Translatize. It holds one file per target language at the files path – locales/de.json, locales/fr.json – written exactly as translatize pull writes them: keys sorted, two spaces of indentation, a trailing newline, empty values left out. Files that would not change are left alone; when none would, the check notes "Translations in this pull request are already up to date." The app's own commit does not start another round – the check just moves to the new commit.

Settings

The GitHub tab holds the settings for the linked repository. A change is saved at once, and open pull requests are checked again with the new settings. A key in the config's github block wins over the tab for that repository.

When the pull request merges or closes

When pull request #42 is merged on GitHub, the app merges pr-42 into the base branch from the GitHub tab, whatever branch the pull request targeted on GitHub:

• If its AI translation is still running, the app waits for it, so the merge includes the result.
• Only what the pull request's branch added or changed is merged, language by language. Everything else on the base branch stays as it is, including changes made there while the pull request was open.
• Keys removed from the source file are not deleted from the base branch.
• A string the pull request changed and later changed back is not merged, so the abandoned text never reaches the base branch.
• Where a key was also edited on the base branch while the pull request was open, the pull request's value wins. The check then reads "Translations merged – recheck 3 keys" and lists them, so someone can look again.
• Then pr-42 is deleted.

If the merge gate is set to Block and finds QA errors, nothing is merged. The check fails with "Translations not merged – QA errors", the branch is kept, and the project's admins and owners get an in-app notification: "Translations for PR #42 were not merged – QA errors". Fix the errors and merge the branch in Translatize; an admin or owner can also override the gate there, with a written reason. If the merge fails for another reason, the check fails with "Translations not merged" and the branch is kept for you to merge in Translatize.

When a pull request is closed without merging, its branch is deleted and nothing is merged. Reopening the pull request starts again with a new branch. The thinking behind a branch per change is in Translation branching explained.

Plans

The GitHub App is part of the Professional ($49 per month) and Agency ($199 per month) plans. What counts is the plan of the account that pays for the project – the project owner, or the workspace owner for a project in a workspace. On Free and Starter, the GitHub tab explains the app and links to the plans.

AI translation of pull request strings uses the plan's monthly AI translation characters: 2,000,000 on Professional and 10,000,000 on Agency. Both plans have unlimited branches, so a branch per pull request never runs into a limit.

If that plan drops below Professional, the connection pauses: the tab shows Paused – plan, and the checks on open pull requests turn neutral with "GitHub sync requires the Professional plan". After an upgrade it resumes by itself – open pull requests are synced again, and pull requests merged or closed in the meantime are merged or cleaned up.

What the app never does

• It never runs, builds or installs anything from your repository. It reads translatize.config.json and the locale files the files pattern names, as JSON, and nothing else.
• It commits only to the branch of an open pull request, only in On request or Automatically mode, and never to a fork.
• It never AI-translates a pull request from a fork.
• It never deletes a Translatize branch it did not create.
• It never deletes keys from your base branch.

On GitHub the app asks for these repository permissions: Contents (read and write – to read the config and locale files and to commit translations), Checks (read and write – for the Translatize check), Pull requests (read) and Metadata (read).

Disconnecting

Disconnect repository at the bottom of the GitHub tab stops GitHub sync and revokes the app's access token. Branches and translations made so far stay in Translatize. The app stays installed on GitHub until you remove it there.

Troubleshooting

On the pull request

In the GitHub tab