Setup

Max Prilutskiy·Updated 2 months ago·2 min read

Set up continuous localization in your CI/CD pipeline in three steps: configure the CLI, add your API key, and choose a workflow.

Prerequisites

You need a working CLI setup with an i18n.json file and the ability to run npx lingo.dev@latest run locally before adding CI/CD.

Step 1. Configure the CLI

If you haven't already, follow the CLI Setup guide. You should end up with:

  • An i18n.json file in your project root
  • An API key (either LINGO_API_KEY for Lingo.dev Engine or a provider key like OPENAI_API_KEY)
  • The ability to generate translations locally with npx lingo.dev@latest run

Step 2. Add your API key as a CI secret

Store your API key in your CI platform's secret management:

GitHub
GitLab
Bitbucket

  1. Navigate to Settings > Secrets and variables > Actions
  2. Click New repository secret
  3. Name: LINGODOTDEV_API_KEY, Value: your API key
  4. Click Add secret

Step 3. Choose a workflow and add the config

Pick the workflow that fits your team, then follow the platform-specific guide:

Workflow Best for
Commit to main Small teams that want zero-friction, invisible translation updates
PR from main Teams that want to review translations before they land on main
Commit to feature branch Teams with long-lived feature branches
PR from feature branch Teams that want maximum control over every translation change

Not sure which to pick? Start with "Commit to main" - it's the simplest. You can switch later without changing your i18n.json.

For platform-specific setup instructions and workflow examples, see:

GitHub Actions
GitLab CI/CD
Bitbucket Pipelines

Verify the setup

After configuring your CI workflow, push a change to trigger it. The integration should:

  1. Run the translation pipeline
  2. Commit translations or open a PR (depending on your workflow)
  3. Update the i18n.lock file

To verify translations are complete in CI without generating new ones, use the --frozen flag:

npx lingo.dev@latest run --frozen

This exits with a non-zero status if any content is untranslated - useful as a deployment gate. See Advanced Patterns for examples.

Next Steps

GitHub Actions
Advanced Patterns
How It Works
Connect Your Engine