GitHub

Translate repository content with the GitHub App while keeping source changes and translated output reviewable.

The Lingo.dev GitHub App makes translated files part of your repository's change history. You commit source content and a translation configuration; the App reads the selected files, translates them through a localization engine, and returns a diff the team can inspect in GitHub.

In the Studio 2.5 navigation, open Studio 2.5 → Integrations instead of Settings → Integrations. Existing connection and setup links still work.

Default-branch changes produce a translation pull request. If you enable pull-request processing, translations join that pull request's branch instead. This page starts with the default-branch workflow and keeps translation delivery separate from the decision to merge it. To run the CLI in your own runner, use the GitHub Actions recipe.

To let your coding agent connect the app, see Set up with a coding agent.

Connect the repository and translation configuration #

In Lingo.dev, open Settings → Integrations and select Connect for GitHub. Connect the App installation to your organization and grant access to the repositories you want it to process. A GitHub organization administrator may need to approve the installation; repository access follows the installation's selected scope.

Choose an accessible localization engine in the connected organization. Its configuration supplies the model choices, glossary, rules, voice, and applicable review behavior. GitHub installation permissions authorize repository work; Lingo.dev permissions authorize use of the localization engine.

Open the connection in Settings → Integrations to inspect its installation and connection health. Manage on GitHub opens the installation's repository-access settings. In Studio, select a repository under Connected, then use Workflow runs alongside the GitHub check and commits to follow a particular source change.

If Studio 2.5 is enabled for your organization, its Source content sidebar lists the repositories your connected installation can access without waiting for a GitHub event. With a valid .lingo/config.json on the default branch, you can open configured JSON and JSONC source files and their existing translations without a new commit or a translation run. Browsing does not use translation credits or enable automatic synchronization. Repositories without valid configuration remain visible; opening their files reports the configuration error.

A connection with one repository appears as a single row, and each repository's files start below the folder they all share, such as src/content/en. Search files above the tree filters GitHub files by name, and the Only changed filter button shows only files with edits you have not sent yet.

Create .lingo/config.json at the repository root. This example selects English JSON catalogs under locales/en/ and produces French files under the corresponding locales/fr/ paths. Replace eng_example with your localization engine ID:

json
{
  "engineId": "eng_example",
  "sourceLocale": "en",
  "targetLocales": ["fr"],
  "files": [
    {
      "pattern": "locales/en/**/*.json",
      "format": "json"
    }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": false }
    },
    "safety": { "requireApproval": true }
  }
}

Complete one inspected run #

The example requires approval before translation starts. To test it:

  1. Commit the configuration and a small source change to the default branch, such as one message in locales/en/checkout.json.
  2. Open the pending GitHub check and approve the run. If approval is unavailable, inspect the approval rules.
  3. Open the translation pull request the App creates or updates. Find locales/fr/checkout.json and compare the changed message with the source.
  4. Build or run the application with the translated file. Check the wording, variables, and locale selection, then review and merge the pull request through your normal repository process.

Approval in step 2 authorizes the translation work and its usage. It does not approve the resulting wording or merge the pull request. If output is missing, use inspection and recovery to identify the incomplete stage.

Adapt the configuration to your file layout #

Source patterns should select only source files. For example, locales/en/**/*.json keeps generated French files out of later source discovery. Patterns are repository-relative; absolute paths and .. are rejected. Each file entry requires a pattern or an include list. A configuration supports up to 100 file entries and 50 unique target locales.

By default, the source locale in a path determines where target files go. When paths do not contain a locale, set targetPath: [locale] supplies the target locale, and [path] supplies the source path after removal of an optional sourceRoot prefix. For instance, sourceRoot: "content" and targetPath: "translations/[locale]/[path]" map content/help/start.md to translations/fr/help/start.md for French. A glob-based template needs both placeholders. sourceRoot requires targetPath and must prefix the selected sources. Single-file, multi-locale formats such as Xcode string catalogs and CSV reject output templates because their translations stay inside the original file.

Use localeFormat when the application needs BCP-47, underscore-separated, or Android locale spelling in paths. Android resources default to Android qualifiers. Confirm the first output path against the application's loader before adding more locales.

Choose when translation runs and where it writes #

Default-branch push processing is enabled by default. Pull-request processing is disabled by default and must be enabled explicitly in the configuration.

Commit a valid .lingo/config.json to the default branch before enabling pull-request work. The App reads the engine ID, github.workflows, and github.safety from that trusted default-branch revision. Pull-request changes to those settings do not authorize a different engine or change the approval policy for their own run. Source locale, file selection, and target locales come from the revision being translated.

TriggerTranslation delivery
Push to the default branchCommits to lingo/translations/<default-branch> and opens or updates a pull request back to the default branch.
Enabled pull-request workflowCommits translation output to the pull request's head branch.
Translation command on a pull requestWrites the requested translation output to that pull request's head branch.

Pull-request delivery requires a writable head branch in the installed repository. The App skips forks and refuses to write this output directly to the default branch.

The App serializes repository work and filters its own generated commits so they do not repeatedly trigger translation. When no configured source changed or targets already cover the requested work, a run can finish without a diff. Its check explains the outcome; forced regeneration is for replacing selected translations, not for making an unchanged run look active.

Require approval before spending on a run #

github.safety.requireApproval defaults to false. Set it to true in the default branch's configuration when someone must authorize a run before translation starts. Default-branch pushes present Approve and Deny controls on the check. For pull requests, the App posts a comment and an authorized reviewer responds with /lingo approve.

When approval is required, failure to create the audit check blocks the workflow. Repair check creation or access before attempting approval again.

Any /lingo translate command, with or without file globs, authorizes the work it requests and bypasses this preliminary approval. Check the file and locale scope before posting it.

Run commands on a pull request #

Comment on an open pull request whose branch belongs to the installed repository and is not the default branch. The App reads the first line of the comment that starts with /lingo. It uses source locale, file options, and target locales from the pull request's head configuration, with the engine and safety settings from the default branch. Only someone with write access to the repository can start translation.

CommandEffect
/lingo or /lingo helpReplies with the list of commands.
/lingo translateTranslates the source changes in this pull request and keeps unchanged translations. It replaces a translation proposal still waiting from the last push.
/lingo translate --locales fr,esTranslates this pull request's source changes for the listed locales only.
/lingo translate <glob>...Creates missing target files for configured sources that match the globs.
/lingo translate <glob>... --forceRegenerates the matching targets, replacing existing translations. --force requires at least one glob.
/lingo translate [<glob>...] --key <pattern>Retranslates matching named keys in existing translations.
/lingo approveApproves the translation proposal waiting on this pull request.

Without globs or --key, a command works from the files the pull request changed, so it runs even when pull-request processing is disabled in the configuration. With globs, it works from the files on the branch, whatever the pull request changed. Globs are relative to the repository root and case-sensitive, and they only reach files that a configured pattern selects. --locales takes a comma-separated list. Codes match the configured target locales regardless of case, and the reply notes any code that matches none of them.

Backfill a selected file or locale and Retranslate keys with context cover the glob and key forms in detail.

Backfill a selected file or locale #

Post a scoped command on a pull request to request one configured file and locale:

text
/lingo translate locales/en/checkout.json --locales fr

For formats with a separate file per locale, this fills a missing French target file. It does not fill missing keys inside an existing target file. Adding --force regenerates the selected output without using the existing target for reuse, so it can replace accepted human edits. Use a narrow file and locale selection, then review the resulting diff.

Xcode string catalogs and CSV files keep source and targets in one file. A plain scoped command fills missing locale entries and retains existing entries, including those whose source has changed. Use /lingo translate without a file pattern to translate source changes in the pull request; this can replace existing translations for those changed entries, including human edits. Add --force with a narrow file and locale selection when you intend to regenerate existing translations. A forced App command rebuilds the selected content; reconstruction retains locales outside the requested scope. For updates through the CLI, follow the String Catalogs or CSV correction procedure.

Retranslate keys with context #

Use --key to retranslate selected named keys in existing translations. For JSON and JSONC files, add --context to explain their meaning or give this run guidance on tone and casing:

text
/lingo translate --key "keyname" --context "button label, keep sentence case"

--context requires --key. Supply context once; it applies to every selected key and locale in the JSON and JSONC files. Other matching formats are translated without that context. Repeat --key for multiple patterns, and use file globs or --locales to narrow the request. Without file globs, the command selects all configured source files. Keys match exactly, by prefix, or by glob; unrelated translations are preserved. Formats without named keys and locales without existing translations are skipped.

GitHub App key commands regenerate unchanged selected strings in YAML and locale-root YAML too. The CLI's key-scoped workflow has different baseline reuse behavior for those formats.

Keep the command on one line. Use single or double quotes around context containing spaces; --context="button label" also works. To include the same quote inside the text, escape it with a backslash, for example --context "Use \"Save\" as a button label". Context is retained with the run for retries and history, but is not saved as engine instructions or inherited by later runs. Existing glossary, placeholder, and output-format rules still apply.

Within quoted context, only \\ and a backslash before the surrounding quote are decoded. Placeholders such as $name and ${name}, sequences such as \n, and punctuation stay literal.

Protect the content that should not change #

The App supports structured catalogs, Markdown-family documents, HTML, subtitles, plain text, CSV tables, Java properties files, and platform resources. Formats describes the individual handlers. Payload is not a selectable GitHub file format.

Select HTML with patterns such as pages/en/**/*.html and pages/en/**/*.htm; both extensions infer html, and an explicit "format": "html" is also accepted. HTML output patches translated text and selected attributes into the source, preserving untouched markup, comments, and formatting. An explicit <html> element gets the target locale in lang; fragments do not gain document wrappers.

Select plain-text files with a pattern that ends in .txt, such as metadata/en/*.txt, or with "format": "txt". A .txt file belongs only to such an entry, and an entry with "format": "txt" selects only .txt files, so a broad pattern such as docs/en/**/* skips LICENSE.txt and a broad txt entry skips images beside the text. Plain text translates each line in place.

Select CSV files the same way, with a pattern that ends in .csv, such as i18n/strings.csv, or with "format": "csv". A .csv file belongs only to such an entry, and an entry with "format": "csv" selects only .csv files. CSV fills the target-locale columns of the source file.

Select Java properties files the same way, with a pattern that ends in .properties, such as src/main/resources/messages_en.properties, or with "format": "properties", so a broad pattern such as src/main/resources/**/* skips application.properties. A source named messages_en.properties gets targets such as messages_de.properties and messages_pt_BR.properties. Java properties translates each value in place, keeps comments and layout, matches lockedKeys, preservedKeys and ignoredKeys as the previous CLI did, and reads lockedPatterns in RE2 syntax.

For a document, select the frontmatter fields and component props that contain translatable text. For a JSON-like catalog, use locked paths to copy source values, preserved paths to retain existing target values, and ignored paths to omit values from output. These choices let a catalog contain text alongside identifiers and links without asking the translator to treat them all alike. Locale injection writes the target locale into the configured output field.

File-entry options #

Place the following fields directly on an object in .lingo/config.json's files array, not under options. The App strictly validates root fields, file entries, GitHub settings, component rules, and locale-injection objects. It ignores the optional i18n section and accepts additional fields within that section. The machine-readable schema is available at GET https://api.lingo.dev/github-app/schema.json.

FieldAccepted shapeDefault or scope
pattern / includeRepo-relative nonempty string / nonempty array of such strings.At least one is required; supplied include takes precedence over pattern. Patterns cannot start with / or contain ...
excludeArray of repo-relative nonempty patterns.Optional; applies to this entry.
formatConfigured format string, including "html".Optional inference; .html and .htm select HTML. Payload is not selectable. This is not a document {type,options} object.
localeFormat"bcp47", "underscore", or "android".Ordinary default is BCP-47; Android format implies Android rendering.
targetPath, sourceRootNonempty repo-relative strings.Optional; follow the output-template rules above.
lockedKeys, preservedKeys, ignoredKeysArrays of nonempty dot/bracket key-path strings.Omitted means []; effects depend on the format handler. These are not raw document JSONPath options.
injectLocaleBoolean or { "enabled": boolean, "key"?: nonempty string }.Omitted disables injection; enabled injection defaults to language when key is absent.
translateFrontmatterFieldsArray of nonempty strings.For Markdown-family documents, omission selects title, description; [] selects none.
translateComponentPropsArray of nonempty prop-name strings or objects with optional component and required nonempty props array.component is a nonempty string or nonempty array of nonempty strings; omission removes the name filter. The field defaults to [].

For example, a JSON entry can include "lockedKeys": ["meta.id"], "preservedKeys": ["links.help"], "injectLocale": { "enabled": true, "key": "meta.locale" } alongside its pattern. A Markdoc entry can select a component title with "translateComponentProps": [{ "component": "Callout", "props": ["title"] }]. The CLI accepts some empty values and warns on some unknown fields that the App rejects; validate App configuration against this schema.

Inspect and recover the first recurring run #

Use the GitHub check and Workflow runs to locate the repository, source revision, localization engine, selected files, locales, and delivery branch. Compare these with the change you expected, then identify where processing stopped:

ObservationWhat to check before requesting more work
Default-branch configuration is missing, invalid, or disables the workflowNo GitHub check or comment is posted. Fix and commit the default branch's .lingo/config.json, including the intended workflow settings.
Source-revision configuration is missing or invalid after the default-branch checks passThe run reports a failing check and, for the applicable PR flow, a comment. Fix the reported source configuration error.
No matching source changes or coverage already presentInspect patterns and selected coverage; a no-op is not a failed translation.
A previously missed PR source changeOn PR synchronization, the workflow can compare with the PR base to recover work missed by its immediate previous-source comparison. Inspect base/current source and target together.
A human edited the PR targetFor formats with separate target files, ordinary PR-delta work protects a target changed from the base when its latest commit author is not the bot. Inspect that edit rather than treating skipped output as missing work.
Some commits exist before a later failureOutput can be committed in batches. Several commits may belong to one run, and a failed later batch does not revert earlier successful commits. Review delivered paths and remaining failures separately.

Output is grouped into commits with a 100-file limit and a 5 MiB grouping threshold. A later failure can leave earlier commits in place. Review the delivered paths and remaining failures before retrying or reverting the run.

Disable the applicable triggers to stop recurring work. Revoke repository access or uninstall the App in GitHub when it should no longer have repository authority. Existing commits, accepted pull requests, and prior usage remain; retain or revert delivered content through your repository's normal process.

Collect activity in Radar #

The connection also supplies GitHub commit activity to Radar. Collect translations for measurement describes the event setup and how to import provider history before running a historical measurement.