Skip to main content

Bitbucket: Installation and configuration

How to install, configure, and link BitBucket to Transifex.

Written by Nina Eleftheriadou

With the Bitbucket integration, you link a Transifex project to a Bitbucket repository and branch, all from the Transifex interface. Transifex then pulls new source content from the repository and pushes translations back as commits or pull requests.

🔒 Available on: All plans · Who can do this: Organization Administrator, or Project Maintainer for the projects they maintain

Before you start, you need:

  • A Bitbucket account with access to the workspace that holds the repository.

  • A YAML configuration that lists the files to sync. You can store it as a file in the repository or paste it during setup (see YAML configuration parameters).

Install the Bitbucket integration in a project

  1. Go to your project Settings > Integrations > Bitbucket > Install.

    Project Settings with the Integrations tab open and the Install button for Bitbucket
  2. On the permission page, click Allow to let the Bitbucket integration make changes in Transifex on your behalf.

    Transifex permission page for the Bitbucket application, with the Allow button
  3. On the Bitbucket integration page, click Authorize.

    Bitbucket integration page with the status Not Authorized and the Authorize button
  4. On Bitbucket, sign in if you need to. Under Authorize for workspace, choose the workspace that holds your repositories, and click Grant access. Transifex asks to read your account information, to read and modify your repositories and their pull requests, and to read and modify your repositories' webhooks.

    Bitbucket access request from Transifex with the Authorize for workspace list and the Grant access button
  5. Select the Bitbucket account to connect with the project. The Bitbucket integration page shows Authorized and the account, and you're ready to link a repository.

    Bitbucket integration page with the status Authorized and the Link Repository button

📝 Note: The Bitbucket integration reads, writes, and deletes only the files that match your YAML configuration. It closes only pull requests that it opened.

Link a project with a Bitbucket repository

On the Bitbucket integration page, click Link Repository. The Link Repository window opens with three steps: Select repo, Select files, and Sync content.

Select your repository

Select the repository to sync with the project, and then select the branch. The repository list shows the repositories you gave Transifex access to when you authorized it.

⚠️ Warning: Branches whose names contain a slash, such as feature/version1, don't sync with Transifex because of a known Bitbucket issue (BCLOUD-20223).

Select repo step with a repository and the master branch selected, and Multi-branching selected

The Bitbucket integration works with this branch only. To also track other branches, select Multi-branching. To learn how the multi-branch feature works, see Working with GitHub/Bitbucket/GitLab/Azure Repos branches.

📝 Note: If your workspace has more than 100 repositories, the repository list becomes a text field. Type the repository as account/repository_slug.

You can link more repositories to the same project later. See Bitbucket: Advanced settings.

Click Next.

Select files

The Bitbucket integration finds the files to sync through a YAML configuration. To write one, see YAML configuration parameters and More examples of YAML configurations. Choose where the configuration lives:

  • Add a path to your YAML configuration file: store the configuration as a file in your repository, enter its path, and click Apply to preview it. By default, the Bitbucket integration looks for the file in the root of the branch you selected, but you can give the file any name, such as transifex.yml, and store it in any folder. The file must already be in the repository.

    Select files step with the path transifex.yml applied, a preview of the configuration, and the message Your configuration is valid
  • Paste your YAML configuration: type or paste the configuration in the text box. The Bitbucket integration tells you whether the configuration is valid as you type.

    Select files step with a pasted configuration, the Test configuration button, and the source file it found

Click Test configuration to see which files the configuration finds, and then click Next.

📝 Note: When the configuration changes, in your repository or in the Bitbucket integration, Transifex syncs automatically:

  • New files in the configuration become new resources in Transifex, with any translations found in Bitbucket. Each resource gets a unique slug, and the repository and branch path are added as resource categories.

  • For resources that are already synced, Transifex imports translation files it finds in Bitbucket for languages that have no translations in Transifex yet.

Sync content

In the last step, choose how content moves between Bitbucket and Transifex.

Pull content from your repository to Transifex

Pulling is automatic. Whenever the selected branch changes, Transifex imports the new and changed content into the project.

Push content from Transifex to your repository

Under When would you like Transifex to push content?, choose when Transifex pushes the translations of a resource in a language:

Sync content step with the push options 100% translated, 100% reviewed, 100% proofread, and Custom

Option

Transifex pushes a language when

Example

100% translated

All strings of the resource are translated in that language

Afrikaans (af) and Greek (el) are 100% translated, and Spanish (es) is 50% translated. Only af and el are pushed.

100% reviewed

All strings are reviewed

af is 100% reviewed, and el and es are 0% reviewed. Only af is pushed.

100% proofread

All strings are proofread

el is 100% proofread, and af and es are 0% proofread. Only el is pushed.

Custom

The percentage you enter (less than 100%) is reached for the status you choose: translated, reviewed, or proofread

The threshold is 60% translated. af is 66.67%, el 83.33%, and es 50% translated. Only af and el are pushed.

Transifex doesn't push languages below the threshold. After a language reaches the threshold, Transifex pushes later translation updates for it automatically.

Choose how translations reach Bitbucket

⚠️ Warning: Transifex can't commit directly to a branch that has branch restrictions in Bitbucket. If your branch has them, choose Create a Pull Request, or change the restrictions in Bitbucket. To learn how, see Use branch permissions.

Under How would you like Transifex to push translations to Bitbucket?, choose one:

  • Create a Pull Request: Transifex creates a branch with the translations and opens a pull request that you review and merge in Bitbucket. If a pull request with earlier translations is still open, Transifex updates it instead. In Group content in your PRs, choose what each pull request contains:

    • No grouping: one pull request for each resource and language.

    • By resource: one pull request for each resource, with all its target languages.

    • By language: one pull request for each language, with all resources.

    • All resources and languages: a single pull request with all resources and target languages.

  • Commit directly: Transifex commits the translations to the selected branch.

Commits and pull requests come from the Transifex bot.

Sync content step with Create a Pull Request selected, the Group content in your PRs list, and the optional settings below

If you use the multi-branch feature, you can keep pull requests for your default branch and commit directly to the other branches. To do this, select Commit directly for branches associated with the multi-branch feature. This option appears only when Multi-branching is selected in the Select repo step.

📝 Note: When you use pull requests:

  • If a language falls below the threshold while its pull request is open, the Bitbucket integration closes the pull request, so no outdated translations wait for review.

  • If you change the threshold, for example from a translated percentage to a reviewed or proofread one, the Bitbucket integration closes the open pull request. It opens a new one when the new condition is met.

For the optional settings at the bottom of this step, see Optional settings in the Sync content tab.

Click Save & Sync to start syncing Bitbucket and Transifex.

Optional settings in the Sync content tab

At the bottom of the Sync content step, you can turn on these settings. They change how translations reach your repository.

The four optional settings at the bottom of the Sync content step

Add a prefix to your commit message

Select Add a prefix to the commit message and enter the prefix, up to 128 characters. The prefix applies to direct commits and to pull requests. Use it, for example, to recognize Transifex commits in your CI/CD pipelines, or to make them easier to find.

Add a prefix to the commit message selected, with the prefix TRANSLATION-UPDATE

With the prefix TRANSLATION-UPDATE, commit messages in Bitbucket start with TRANSLATION-UPDATE.

Bitbucket commit list with a commit message that starts with TRANSLATION-UPDATE

Add a prefix to the pull request title

Select Add a prefix to the Pull Request title and enter the prefix, up to 128 characters. Use it, for example, when your repository has naming rules for pull requests, or to filter Transifex pull requests in your CI/CD pipelines.

Add a prefix to the Pull Request title selected, with the prefix NEW-PR-TITLE

With the prefix NEW-PR-TITLE, pull request titles in Bitbucket start with NEW-PR-TITLE.

Bitbucket pull request list with a pull request titled NEW-PR-TITLE Updates for file

Receive updates for source files

Select Receive updates for source files to sync changes you make to source files in Transifex back to your repository, with no manual steps.

Receive updates for source files selected in the Sync content step

📝 Note: Not every file format lets you update the source in Transifex. To check which formats do, see Updating your source content.

Add an interval between commits

Select Add an interval between commits and enter a number of minutes, up to 60. Instead of a commit for every translation update, Transifex waits for the interval to end and commits all the updates made during it. This keeps many small commits of the same file out of your repository.

Add an interval between commits selected, with 5 minutes entered

For example, you set the interval to 10 minutes and edit several translations of one language in one resource. When the 10 minutes are up, Transifex sends one commit with all the edits. Edits you make after that go into the next commit, 10 minutes later.

📝 Note: The interval groups updates over time, not across resources or languages. Each pair of a resource and a language still gets its own commit. For example, if you edit two languages of the same resource, you see two commits in Bitbucket, one for each language. If you edit two resources in the same language, you also see two commits, one for each resource.

YAML configuration parameters

The configuration must start with a top-level git: key. Under it, add a filters list and, optionally, a settings section. Each entry in filters starts with - filter_type: and describes one set of source files. Add an entry for each file type or location you want to sync.

Filter parameters

Parameter

Filter types

Description

filter_type

All

file for one source file, dir for all files with one extension in a directory, or dynamic for paths matched with placeholders

file_format

All

The i18n type of the files, such as PO. To find the i18n type of each format, see File Formats

source_language

All

The source language of your project, such as en. It's the language you selected when you created the project

source_file

file

Path to the source file

source_file_dir

dir

Path to the directory with the source files

source_file_extension

dir

Extension of the source files, without the dot, such as strings

source_files_expression

dynamic

Path expression for the source files, with the <dir> and <file> placeholders

translation_files_expression

All

Path expression for the translation files. It must contain <lang>, such as 'translations/po/<lang>.po'. Surround it with single quotes

mode

All (optional)

The download mode for the translation files, such as onlytranslated. Modes depend on the file format; see the format's page in File Formats

ignore_dirs

dir, dynamic

A list of directories to skip

ignore_files

dir, dynamic

A list of files to skip

Paths: write every path in full from the root of the repository, even when the configuration file is in a subfolder, because the Bitbucket integration always searches from the repository root. Don't start a path with a forward slash. Don't put quotes around source_file, source_file_dir, or source_files_expression.

📝 Note: mode doesn't work for XCSTRINGS files.

Placeholders

Placeholder

Replaced with

Example

<lang>

The code of each target language, or your own code if you set a language mapping

translations/po/<lang>.po becomes translations/po/el.po for Greek

<file>

A file name, without its extension

folder/<file>.po matches folder/foo.po and folder/bar.po

<dir>

One or more folders

<dir>/<file>.po matches folder/foo.po and f1/f2/f3/foo.po

<br_unique_id>

A unique ID that the Bitbucket integration generates for each pull request branch. Used in pr_branch_name

tx_translations_<br_unique_id>

Settings parameters

These go under settings:, inside git: and at the same level as filters:.

language_mapping

If your files use language codes other than the standard ISO codes (ISO 639-1, ISO 639-2, or ISO 639-3), map each Transifex language code to your code. On each line, the Transifex code comes first and your code second.

git:
settings:
language_mapping:
pt_BR: pt-br
zh_CN: zh-cn

📝 Note: Language mapping changes only the file names of the translation files, so they follow your naming conventions.

pr_branch_name

The name of the branch the Bitbucket integration creates for a pull request. Include <br_unique_id> so each branch name is unique.

git:
filters:
- filter_type: file
file_format: KEYVALUEJSON
source_language: en
source_file: source/example.json
translation_files_expression: 'translations/<lang>/example.json'
settings:
pr_branch_name: branch_name_<br_unique_id>

For complete configurations, see More examples of YAML configurations.

More examples of YAML configurations

Sync a single file

git:
filters:
- filter_type: file
file_format: PO
source_file: locale/example.po
source_language: en
translation_files_expression: 'Translations/<lang>/example.po'

Sync multiple files of a single file type

git:
filters:
- filter_type: dir
file_format: STRINGS
source_file_extension: strings
source_language: en
source_file_dir: locale/DirTest
translation_files_expression: 'Translations/<lang>'

Sync a single file using a specific download mode

git:
filters:
- filter_type: file
file_format: YML
source_language: en
source_file: test.yml
translation_files_expression: 'Translations/target_<lang>.yml'
mode: onlytranslated

Sync several filters from the same directory

When two file filters match source and translation files in the same directory, put the more specific filter first.

Example: a specific file before a general one

git:
filters:
- filter_type: file
file_format: YML
source_language: en
source_file: config/locales/simple_form.en.yml
translation_files_expression: 'config/locales/simple_form.<lang>.yml'

- filter_type: file
file_format: YML
source_language: en
source_file: config/locales/en.yml
translation_files_expression: 'config/locales/<lang>.yml'

Example: two file types in one directory

git:
filters:
- filter_type: dir
file_format: STRINGS
source_file_extension: strings
source_language: en
source_file_dir: locale/DirTest
translation_files_expression: 'Translations/<lang>'

- filter_type: dir
file_format: KEYVALUEJSON
source_file_extension: json
source_language: en
source_file_dir: locale/DirTest
translation_files_expression: 'Translations/<lang>'

Sync multiple files, excluding specific paths or files

git:
filters:
- filter_type: dir
file_format: KEYVALUEJSON
source_file_extension: json
source_language: en
source_file_dir: localization_project/
translation_files_expression: 'localization_project/translations/<lang>/'
ignore_dirs:
- localization_project/path2/
- localization_project/path3/
ignore_files:
- localization_project/path1/example2.json
- localization_project/path1/example4.json

Sync files with a specific branch name and language mapping

git:
filters:
- filter_type: file
file_format: STRUCTURED_JSON
source_language: en
source_file: locale/example.json
translation_files_expression: 'Translations/<lang>/example.json'

settings:
pr_branch_name: tx_translations_<br_unique_id>
language_mapping:
es_419: es-419
pt_BR: pt-br
zh_CN: zh-cn
zh_TW: zh-tw

Examples of the dynamic filter type

With filter_type: dynamic, the <dir> and <file> placeholders match source file paths, and the same placeholders build the translation file paths. ignore_dirs and ignore_files work with this filter type too.

Example 1: source files in one folder

git:
filters:
- filter_type: dynamic
file_format: PO
source_language: en
source_files_expression: folder/<file>.po
translation_files_expression: 'locale/<lang>/<file>.po'

With the target languages Greek (el) and German (de), this configuration matches:

Source file

Translation files

folder/foo.po

locale/el/foo.po, locale/de/foo.po

folder/bar.po

locale/el/bar.po, locale/de/bar.po

Example 2: source files in any folder

git:
filters:
- filter_type: dynamic
file_format: PO
source_language: en
source_files_expression: <dir>/<file>.po
translation_files_expression: '<dir>/<lang>/<file>.po'

With the target languages Greek (el) and German (de), this configuration matches:

Source file

Translation files

folder/foo.po

folder/el/foo.po, folder/de/foo.po

f1/f2/f3/foo.po

f1/f2/f3/el/foo.po, f1/f2/f3/de/foo.po

More examples of the dynamic filter type

Example 3

git:
filters:
- filter_type: dynamic
file_format: GITHUBMARKDOWN
source_language: en
source_files_expression: docs/guides/<dir>/source/<file>.md
translation_files_expression: '<lang>/<dir>/translations/<file>.md'

Example 4

git:
filters:
- filter_type: dynamic
file_format: GITHUBMARKDOWN
source_language: en
source_files_expression: docs/guides/<dir>/source/<file>.md
translation_files_expression: '<lang>/<dir>/translations/<file>/product_feature_A.md'


💡 Tip

Looking for more help? Get support from our Transifex Community Forum!

Find answers or post to get help from Transifex Support and our Community.

Did this answer your question?