Lingo.dev Bitbucket Integration

Lingo.dev Bitbucket Pipelines Integration is a secure, open-source CI/CD integration that automatically localizes new content and prevents incomplete translations from reaching production. It creates pull requests or commits directly to your branch, depending on your team's workflow requirements.

It also implements automatic conflict resolution through rebasing, so your translations stay synchronized with your code without manual intervention.

The integration supports multiple workflow scenarios:

Direct commits to branches when content changes are pushed
Pull requests targeting branches for translation updates

Upon completion this guide, you will:

Set up automated localization triggered by code pushes;
Configure secure authentication using repository variables;
Choose between direct commits or pull request workflows;
Understand how continuous localization fits into your existing process.

Let's begin!

Prerequisites

Repository Setup

Your repository must have Lingo.dev CLI configured with a valid i18n.json file. If you haven't set this up yet, complete the CLI quickstart first.

Step 1. Authentication Setup

Lingo.dev Bitbucket Integration needs access to your translation engine and repository. Authentication happens through repository variables that keep your credentials secure.

Add Your API Key

Navigate to your repository Repository settings → Repository variables, then add your translation engine credentials:

For raw LLM API users:

Variable name: OPENAI_API_KEY or ANTHROPIC_API_KEY
Variable value: Your API key from the respective provider

For Lingo.dev Engine users:

Variable name: LINGODOTDEV_API_KEY
Variable value: Your project API key from lingo.dev/app

Add Bitbucket Access Token (For Pull Request Mode)

If you plan to use pull request mode, create an access token:

Go to Repository settings → Access tokens → Create Repository Access Token
Grant these scopes:
- Read & write repositories
- Read & write pull requests
Add the token as a repository variable:
- Variable name: BB_TOKEN
- Variable value: Your Bitbucket access token

Step 2. Create the Workflow

Create or update your bitbucket-pipelines.yml file with this basic configuration:

script:
  - pipe: lingodotdev/lingo.dev:main

This configuration uses the Lingo.dev pipe and runs the translation engine automatically.

Required Permissions

Bitbucket Pipelines requires access to repository variables and git operations:

Repository Variables:

LINGODOTDEV_API_KEY — Required for Lingo.dev Engine users
OPENAI_API_KEY or ANTHROPIC_API_KEY — Required for raw LLM API users

For Pull Request Mode:

BB_TOKEN — Required for creating and managing pull requests

Access Token Scopes (when using pull request mode):

Read & write repositories — Access and modify repository content
Read & write pull requests — Create and manage pull requests

These permissions allow the integration to read your content, generate translations, and update your repository with the localized content.

Step 3. Choose Your Workflow Mode

Lingo.dev Bitbucket Integration supports two operational modes depending on your team's code review requirements.

Direct Commit Mode (Default)

The integration commits translations directly to your branch:

script:
  - pipe: lingodotdev/lingo.dev:main

This mode works best for:

Solo developers or small teams
Feature branches that will be reviewed before merging
Projects where translation updates don't require separate review

Pull Request Mode

The integration creates pull requests for translation updates:

script:
  - pipe: lingodotdev/lingo.dev:main
    variables:
      LINGODOTDEV_PULL_REQUEST: "true"

Required Setup for Pull Request Mode

Repository Variables: Both LINGODOTDEV_API_KEY and BB_TOKEN must be configured as repository variables.

Access Token Requirements: Your BB_TOKEN must include read & write permissions for both repositories and pull requests.

Note: The BB_TOKEN variable is required when using pull request mode.

This mode works best for:

Teams with strict code review requirements
Projects where translation changes need separate approval
Workflows that require explicit review of all changes

Step 4. Workflow Scenarios

Lingo.dev Bitbucket Integration adapts to different development workflows. Understanding these scenarios helps you choose the right configuration for your team.

Scenario 1: Feature Branch Updates (Direct Commits)

Trigger: Push to feature branches Action: Commits translation updates directly to the feature branch

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main

Flow: Content changes pushed to feature branch → Integration commits translations to the same branch

This keeps translation updates within the feature branch, ensuring translations are reviewed alongside the original changes.

Scenario 2: Pull Requests for Updates (Pull Request Mode)

Trigger: Push to any configured branch Action: Creates pull request with translation updates

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}" # or OPENAI_API_KEY/ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

Flow: Content changes pushed to branch → Integration creates pull request with translations

This maintains separate reviews for translation updates.

Advanced Configuration

Customize the integration behavior using additional variables:

Example with Lingo.dev Engine:

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}"
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

Example with raw LLM API:

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                OPENAI_API_KEY: "${MY_OPENAI_API_KEY}" # or ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

Configuration options:

LINGODOTDEV_API_KEY — Your Lingo.dev Engine API key, if you're using Lingo.dev Engine
OPENAI_API_KEY — Your OpenAI API key, if you're using raw LLM API
ANTHROPIC_API_KEY — Your Anthropic API key, if you're using raw LLM API
LINGODOTDEV_PULL_REQUEST — Create pull request instead of direct commit (default: false)
LINGODOTDEV_PULL_REQUEST_TITLE — Custom pull request title (default: feat: update translations via @lingodotdev)
LINGODOTDEV_COMMIT_MESSAGE — Custom commit message (default: feat: update translations via @lingodotdev)
LINGODOTDEV_WORKING_DIRECTORY — Run the integration in a subdirectory (default: .)
LINGODOTDEV_PROCESS_OWN_COMMITS — Process commits made by this integration (default: false)
BB_TOKEN — Bitbucket access token (required for pull request mode)