Table of Contents

To begin you require three basic steps:

  1. Authorize your Transifex organization with your Bitbucket account.

    Navigate to Organization settings > Manage Integrations and click the "Authorize" link and then the "Authorize the Transifex app" link under the Bitbucket widget.

  2. Link your Transifex project with a specific Bitbucket repository

    Navigate to the project of your choice or create a new project and visit the Project settings page. In there, you will see a tab reading “Integrations”. If the integration is set up as described in the previous step, you will see the BitBucket option along with a button to Link Repository.


    Clicking on that button, the BitBucket Integration wizard will pop up to manage the setup.

    On the first step of the wizard, select the BitBucket repository and branch to sync with the project.


    Available repositories listed are the ones you authorized when you installed the Transifex app on the BitBucket account you used for the integration. At this point, the BitBucket integration works on top of a single branch.

    When you are done with this step, hit Next to set up the repository files that are related to localization. The way of giving directions on how the integration works will be through a YML config file called “transifex.yml” (but you can name it as you wish). By default, the integration is looking for this file on the root of the branch repo selected in the previous step.

    However, you have the option to store the file in any folder of your choice. Before proceeding with the next step of the wizard, make sure that this file is available in your repo. After that, press "Apply" so that you preview your file within the Transifex wizard as follows:


    When done hit Save & Sync to link your Transifex project to your Bitbucket repository and branch.

    Note: Whenever your config file is updated in your BitBucket repository, Transifex is getting notified and automatically a sync process between the 2 systems is triggered.

  3. Checking Bitbucket integration link status

    Having the Bitbucket integration active, navigate to your project Settings > Integration tab. There you will be able to see the sync status for the integration, displaying the last time the integration synced data from Bitbucket to Transifex.

Branch names that contain slashes like feature/version1 won't be synced with Transifex due to a known BiBucket issue documented here.

In the meantime, as a workaround, please use branch names without slashes.

Syncing existing resources with Bitbucket

In case your localization process is already in progress, and your projects/resources have already been created in Transifex, you can still use the Bitbucket integration syncing your existing content stored in Transifex with your files hosted in Bitbucket. All you need to do is to execute the steps indicated in the previous section.

Once the process is completed, you will notice that the slug of your TX resources are updated following the schema: slug = "filename-extension--<branch name>" where filename is the name of the file stored in Bitbucket, extension is the extension of the file, and <branch name> is the name of the Bitbucket branch you've selected while setting this integration up.


  • Let's assume that the source file with the filename android.xml is stored in Bitbucket and you have already uploaded it to Transifex.

  • Once the TX resource is created, Transifex automatically generates a resource slug of the format: androidxml

  • When you sync this resource with Bitbucket, the system will locate the correct TX resource and then it will change the resource slug from androidxml to android-xml--master as you can see below:

  • Before syncing, ensure that the slug of the resources in Transifex follows the schema "filenameextension".

  • Do not manually change the resource slug to "filename-extension--<branch name>".

YAML Configuration Parameter Descriptions

The following are the parameters that are used for the YAML Configuration:

  • filter_type: This specifies a directory or file; the 2 valid values are either "dir" or "file" (without quotes).

  • source_file: Only used for the file filter_type. This points to the location of the source file. The location should not start with a forward slash, and should not be surrounded by either double or single quotes.

  • source_file_dir: Only used for the directory (dir) filter_type. Works the same as source_file.

  • source_file_extension: Only used for the directory (dir) filter_type.

  • file_format: This sets the type of the resources in your project, e.g. to PO. See the File formats section for details about the i18n type of each format available.

  • source_language: This is the source language of your project, such as en for English. This is the language you selected when you created your project.

  • translation_files_expression: A path expression that reflects the file/directory structure of your translation files. The expression must contain the <lang> keyword, denoting where the file paths differentiate per language, e.g. translations/po/<lang>.po; the <lang> keyword will automatically be replaced by the appropriate target language file format. The expression should not start with a forward slash, and should be surrounded by single quotes.

  • language_mapping: If you use language codes other than the standard ISO ones (ISO 639-1, ISO 639-2 or ISO 639-3), the integration lets you set up custom one-to-one language mappings. You'll just need to add a language_mapping section to the YAML configuration file.


The REMOTE_CODE is the language code supported by Transifex. And the LOCAL_CODE is your language code.

The configuration follows a YAML syntax, and users can define a list of individual files or use regular expressions to match multiple files at once. Illustrated examples can be found below:

  • pr_branch_name: If you want to specify the name that will be used for a PR when pushing translations back to Github then you can use this parameter under the settings options like the following example. Please note that <br_unique_id> is a string hash that is automatically generated by the system.

  • ignore_dirs: If you want to exclude one or more than one directory/folder (include absolute paths when using this parameter), then you can include this parameter in your configuration file as follows:

  • ignore_files: If you want to exclude one or more than one localization file (include absolute paths when using this parameter), then you can include this parameter in your configuration file as follows:


You can have multiple entries beneath the opening "filters:" keyword for different source file types or different source file locations. Each entry begins with "- filter_type: ".

Check the section More Examples of YAML Configurations, for samples.

More Examples of YAML Configurations

  • Synching a Single File:

- filter_type: file
file_format: PO
source_file: locale/example.po
source_language: en
translation_files_expression: 'Translations/<lang>/'
  • Synching Multiple Files of a Single File Type:

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

Order matters!

When using two file filter configurations for source/translation files that exist under the SAME directory, the most specific filter should be placed first, just as the following example:

- 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'
  • Synching Multiple Files of Different File Types:

- 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>'
  • Synching Multiple Files excluding specific paths/localization files:

- 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>/'
- localization_project/path2/
- localization_project/path3/
- localization_project/path1/example2.txt
- localization_project/path1/example4.txt

Synching Content from Bitbucket

Syncing content from Bitbucket to Transifex happens either upon saving or updating the integration settings on the project level or automatically whenever new content is found on Bitbucket (after a commit on the branch that is associated with the integration).

When a syncing process is initiated, you will be able to see that syncing is in process in your Project settings > integrations tab under Bitbucket. This process could take some time, depending on the number and size of the files that are syncing.

On Project settings > integrations tab you will also be able to see details about the latest syncing with Bitbucket, so that you can detect any possible issues with specific files that either failed to be synced or weren’t found so that you can take some action to fix them.

Manual Sync

There is an option to send localized content to Bitbucket manually, without waiting for a resource to be 100% translated or reviewed. There is a "Send to Bitbucket" option available on the Projects settings > Integrations tab in the Bitbucket card.


By Clicking on "Send to Bitbucket", a modal will appear requesting for the threshold localization percentage that Transifex will check on all your project's resources.


All target languages that are localized above that threshold will be synced with Bitbucket using the Sync content options you have setup for the integration. For example, if you setup the Bitbucket integration to Sync 100% translated resources by creating a commit to the selected branch, the manual process will identify all target languages whose translation percentage is equal or above the threshold percentage you set on the modal, thereby creating a commit for each target language.

The Threshold percentage can be anywhere from 1 - 100%.


Sending less than 100% translated content to Bitbucket will include untranslated content either as empty or containing the source string as the translation. This depends on the file format.

The manner in which this functions is equivalent to selecting the download for use option in the UI or the default mode in the CLI and API.

In order to get a more detailed description about how the default translation pull mode behaves for a particular file format, visit the links below depending on your file format.

Editing the Project-Bitbucket Link

As your project evolves, you might end up in situations where you want to either extend the files you are syncing from Bitbucket or change the workflow of pushing localized content back on Bitbucket. To edit your options visit your Projects settings > integrations tab and click on the button in the Bitbucket integration. The interface to make the changes is the same as the one of the initial setup, but you will only be able to:

  • Update the detected files in the Bitbucket repository, by changing the YAML configuration.

  • Change options on how updates from Transifex are sent back to Bitbucket.

Please note that if you remove an already synced file or directory from the YAML configuration, the associated resource(s) will no longer be synced with the corresponding file(s) in Bitbucket.

Please keep in mind that when you change your YML configuration file in Bitbucket:

  • Transifex resources are affected - If previously synced resources cannot be found in the updated configuration file, the corresponding resources in Transifex will automatically be deleted from your project

  • When a resource is deleted, strings’ metadata like review state, tags, and screenshot mappings is also removed from Transifex

Commit and PR Messages from Transifex on Bitbucket

Any commits or PRs that are opening due to the integration are happening from a Bitbucket user called Transifex-localization-platform[bot].

back to top

Continue Reading

Content Management



Help Center



Did this answer your question?