Bitbucket Integration

The Bitbucket integration keeps localization files in sync between a Bitbucket repository and your Localizely project, so developers and translators can each work in the tool they know without passing files around by hand.

It works in both directions. Localizely pulls localization files from the repository, either on demand or automatically through a webhook whenever your team pushes code. When translations are ready, Localizely pushes them back by opening a pull request in your repository, so the updated files go through your normal review before they are merged.

Setup

1. Add a localizely.yml file to your repository

The integration reads a localizely.yml configuration file from your repository to learn which files to pull from Bitbucket and which files to push back. Here is a minimal configuration for a Flutter project:

config_version: 1.0 # Only 1.0 available
project_id: 33d9e1a5-6ba8-4b36-a354-47389c432f42 # Your project ID from: https://app.localizely.com/projects
file_type: flutter_arb
upload:
  files: # List of files for upload to Localizely. Usually it is just one file used for the main locale
    - file: lib/l10n/intl_en.arb
      locale_code: en
download:
  files: # List of files for download from Localizely.
    - file: lib/l10n/intl_en.arb
      locale_code: en
    - file: lib/l10n/intl_de.arb
      locale_code: de
    - file: lib/l10n/intl_es.arb
      locale_code: es

The configuration file page covers every available option, including other file formats.

2. Create a Bitbucket access token

Localizely authenticates with Bitbucket using a repository access token. On Bitbucket, open your repository's settings and go to Access tokens. Create a new token, give it a name, and grant it the repository:write and pullrequest:write scopes.

A workspace or project access token works too, as long as it has the same two scopes.

Copy the token as soon as it is created. Bitbucket shows it only once.

3. Connect your repository

In Localizely, the project owner and project admins connect the repository. Open the project's Settings page and select Bitbucket Integration in the Integrations section, then:

Your access token is stored encrypted and is never shown in full again after you save it.

Pulling files from Bitbucket

Manual pull

On the project's Settings page, open Integrations > Bitbucket and click Pull now. Localizely reads the files listed in the upload section of your configuration and imports any new or changed strings.

Automatic pull

Once a manual pull works, set up a webhook so Localizely pulls automatically every time code is pushed to the connected branch. New strings reach your translators minutes after a developer commits them, with no one having to remember to sync.

In Bitbucket, open your repository's settings, go to Webhooks, and click Add webhook. Give it a title, paste the Webhook payload URL from the integration details in Localizely into the URL field, and keep the Push trigger selected under Repository. Then save the webhook.

Pushing files to Bitbucket

When the translations are ready, open Integrations > Bitbucket on the project's Settings page and click Push now. Localizely then:

Your team reviews and merges the pull request on Bitbucket like any other change. Localizely never commits directly to the connected branch.

Frequently asked questions

Can I link one Localizely project to several repositories?

This integration connects a Localizely project to a single Bitbucket repository. To keep additional repositories in sync with the same project, use the CLI or the REST API.