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
Go to your project Settings > Integrations > Bitbucket > Install.
On the permission page, click Allow to let the Bitbucket integration make changes in Transifex on your behalf.
On the Bitbucket integration page, click Authorize.
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.
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.
📝 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).
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.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.
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:
Option | Transifex pushes a language when | Example |
100% translated | All strings of the resource are translated in that language | Afrikaans ( |
100% reviewed | All strings are reviewed |
|
100% proofread | All strings are proofread |
|
Custom | The percentage you enter (less than 100%) is reached for the status you choose: translated, reviewed, or proofread | The threshold is 60% translated. |
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.
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.
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.
With the prefix TRANSLATION-UPDATE, commit messages in Bitbucket start 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.
With the prefix NEW-PR-TITLE, pull request titles in Bitbucket start with NEW-PR-TITLE.
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.
📝 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.
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 |
| All |
|
| All | The i18n type of the files, such as |
| All | The source language of your project, such as |
|
| Path to the source file |
|
| Path to the directory with the source files |
|
| Extension of the source files, without the dot, such as |
|
| Path expression for the source files, with the |
| All | Path expression for the translation files. It must contain |
| All (optional) | The download mode for the translation files, such as |
|
| A list of directories to skip |
|
| 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 |
| The code of each target language, or your own code if you set a language mapping |
|
| A file name, without its extension |
|
| One or more folders |
|
| A unique ID that the Bitbucket integration generates for each pull request branch. Used in |
|
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
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
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 |
|
|
|
|
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 |
|
|
|
|
More examples of the dynamic filter type
Example 3
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
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.

















