Lingo.dev keeps translations in sync with your code. On every change, it detects what content changed, translates it using your connected localization engine - with glossary rules, brand voice, and per-locale model configuration applied consistently - and commits the results or opens a pull request. Incomplete translations never reach production.
Choose your integration#
Each integration has its own guide. Pick the one that matches your setup:
| Integration | How it runs |
|---|---|
| GitHub App | Install once. Lingo.dev runs localization for you on pushes to the default branch, and on pull requests when enabled - no runner, no API key secret, no lockfile. |
| GitHub Actions | Runs the CLI in your GitHub Actions pipeline via the official Action. |
| GitLab CI/CD | Runs the CLI in GitLab pipelines via the official Docker image. |
| Bitbucket Pipelines | Runs the CLI in Bitbucket pipelines via the official Pipe. |
Apart from the GitHub App, every integration runs the Lingo.dev CLI - so any CI/CD environment with Node.js can run localization directly, even without a first-party integration.
How the GitHub App works#
Install the app once and add a .lingo/config.json to the repository. From then on, Lingo.dev runs localization for you - no pipeline, no API key secret, no lockfile:
- Watches for changes - reacts to pushes on the default branch out of the box, and to pull requests once you enable
onPullRequest, checking changed files against the source patterns you configure - Translates the delta - sends changed source content through the engine named by
engineId - Writes results back to GitHub - on default-branch pushes it opens or updates a translation pull request; on pull requests it commits translated files to the PR branch and posts a status comment
- Recovers and batches - detects changes missed by an earlier run and splits very large updates across multiple commits
You can gate runs behind an approval step or trigger translations manually with /lingo commands in a pull request. See the GitHub App guide for the full configuration.
How the pipeline integrations work#
The GitHub Action, GitLab CI/CD, Bitbucket Pipelines, and the standalone CLI all run the same Lingo.dev CLI as a step in your existing pipeline. They need two things: your i18n.json configuration and an API key.
On each run, the integration:
- Discovers source files - reads your bucket configuration to find translatable content
- Detects changes - compares against the
i18n.locklockfile to identify new or modified strings, so only the delta gets translated - Translates - sends changed content through your configured localization engine with all rules applied - glossary, brand voice, per-locale model settings
- Writes results - updates target locale files in place
- Commits or opens a PR - depending on the workflow you choose
Because only changed strings are translated, runs are fast and cost-efficient - even across dozens of locales.
Workflow options#
GitHub App#
The App's behavior is configured in .lingo/config.json:
| Option | What it does |
|---|---|
Push to default branch (onPushToDefaultBranch) | Enabled by default. Opens or updates a translation PR when source changes land on the default branch. |
Pull request translation (onPullRequest) | Disabled by default. Commits translations to the PR branch as the PR changes. |
Approval gate (requireApproval) | Disabled by default. Requires Approve/Deny on the check run, or /lingo approve on a PR, before automatic runs translate. |
Manual commands (/lingo translate) | Backfill or force translations for specific files from a PR comment, any time. |
See the GitHub App guide for full config and command reference.
GitHub Action, GitLab CI, Bitbucket, and CLI#
Four workflow patterns cover most team setups:
| Workflow | Trigger | Output |
|---|---|---|
| Commit to main | Push to main | Translations committed directly to main |
| PR from main | Push to main | Pull request with translations |
| Commit to feature branch | Push to feature branch | Translations committed to the branch |
| PR from feature branch | Push to feature branch | Pull request from the branch |
The first option - commit to main - is the simplest. Translations appear automatically with zero developer intervention. The PR-based options add a review step before translations land.
For details on choosing between these, see Advanced Patterns.
