Table of Contents
Installing the BitBucket integration in a specific project
To install the standalone integration that connects Transifex and BitBucket, you need to perform the following steps:
Go to your project Settings > Integrations > BitBucket > Install
You will be redirected to the integration’s authorization page, where:
First, it is necessary to grant permission for the integration to perform modifications in Transifex on your behalf.
Next, it is required to authorize the integration in your BitBucket account. To do this, select the Authorize button and log into your BitBucket account (if you haven't already done so).
Select the BitBucket account you would like to connect with your project. You are now ready to link a repository.
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. |
Linking a specific project to a BitBucket repository
Clicking on the Link Repository 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. The 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.
For the Multi-branching feature, you can find more information here.
When you are done with this step, hit Next to set up the repository files that are related to localization. There are two ways to select what BitBucket files will be synced with your Transifex project:
The first one is through a YML config file called “transifex.yml” (but you can name it as you wish). This file will be hosted in your BitBucket repository. You can check the following sections for more details:
By default, the integration looks for this file on the root of the branch repo selected in the previous step. However, you can 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" to preview your file within the Transifex wizard:
The second option is to add the configuration directly in the integration using the text box provided. You will be notified if the configuration is valid as you type.
Regardless of the synchronization option you select for your files, you can validate the detected files based on the specified paths in your configuration by selecting the "Test configuration" button. Upon completion, click the Next button to establish a connection between your Transifex project and your BitBucket repository and branch.
Note
Whenever your config file is updated in your BitBucket repository or from within the integration, Transifex is notified, and a sync process between the two systems is triggered automatically.
Whenever new files are added to the configuration file, new resources will be created in Transifex that include any translations obtained from BitBucket. These resources will be identified by a unique slug. The BitBucket repository and branch path will be added as categories for these resources.
Regarding existing resources that have already been synchronized with BitBucket, if translations are detected in your BitBucket repository and no translations for that language exist in Transifex, these newly detected translation files will be sent to Transifex.
By selecting the Next button, you will be directed to the last step of the configuration, in which you will establish the mechanism through which the synchronization between Transifex and BitBucket will take place.
Pulling content from the designated BitBucket repository and branch happens automatically upon changes on that branch.
To push localized content from Transifex back to BitBucket, you have the following options:
Push translations to BitBucket when a language becomes:
100% translated or
100% reviewed or
100% proofread
Additionally, if a language is already fully translated/reviewed/proofread and translations are updated in Transifex, the updated translations will be sent to your repo automatically.
Push translations to BitBucket via:
Pull Request on that branch, which will create a new branch with the localized content and open a Pull Request on the branch that you can later merge directly from BitBucket.
Commit back to the selected branch.
When you finish this setup, you can click Save & Sync to start syncing content from BitBucket to Transifex.
Warnings
In case your branch is protected, you either have to remove the protection of that branch as described here or change the integration settings to create a PR instead of committing directly to the branch.
Syncing existing resources with Bitbucket
Suppose your localization process is ongoing, and your projects/resources have been established in Transifex. In that case, you can still leverage the BitBucket integration to synchronize the content already present in Transifex with the files residing in BitBucket. All you need to do is execute the following steps:
Locate the TX resources in your selected BitBucket repository and branch.
Note the path of each resource in the BitBucket repository,
e.g.,
https://bitbucket.com/transifex/BitBucket-Transifex-Integration/blob/master/source/product_A.jsonKeep the following details separately:
Repository name, e.g., transifex/BitBucket-Transifex-Integration
Branch name, e.g., master
The full path name of the resource, e.g., source/product_A.json
Construct a temporary text using the following pattern:
bitbucket#{full_repo_name}#{branch_name}#{source_file_path}e.g.
bitbucket#transifex/BitBucket-Transifex-Integration#master#source/product_A.json
Generate a hash for this text using the md5 algorithm, e.g., 4e18446ca9ed69e98e4846aca5a1d816 (Tip: you can use an online generator, like
Edit the resource settings for each resource and add the generated hash as a slug.
YAML Configuration Parameter Descriptions
The following are the parameters that are used for the YAML Configuration:
git: This is what the top line of your configuration file should contain.
filter_type: The three valid values are
dirfor directory,file, anddynamic.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 resources in your project, e.g., PO. See the File formats 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 appropriate target language file format will automatically replace the <lang> keyword.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 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 BitBucket, 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:
git:
filters:
- 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
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>'
Warning: Order Matters!
In cases where there are two file filter configurations for source and translation files within the same directory, prioritize the more specific filter by placing it first. The following example can illustrate this.
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'
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>'
Synching Multiple Files excluding specific paths/localization 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.txt
- localization_project/path1/example4.txtSynching File with a specific branch name and with 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-twdynamicfilter type examples (ignore_dirs, ignore_files are also supported in this filter type)git:
filters:
- filter_type: dynamic
file_format: PO
source_language: en
source_file_expression: folder/<file>.po
translation_files_expression: 'locale/<lang>/<file>.po'
Examples of possible source file matches:
git:
filters:
- filter_type: dynamic
file_format: PO
source_language: en
source_file_expression: <dir>/<file>.po
translation_files_expression: '<dir>/<lang>/<file>.po'Examples of possible matches:
Other examples of
filter_type: dynamic#1:
git:
filters:
- filter_type: dynamic
file_format: PO
source_language: en
source_files_expression: docs/guides/<dir>/source/<file>.md
translation_files_expression: <lang>/<dir>/translations/<file>.md#2:
git:
filters:
- filter_type: dynamic
file_format: PO
source_language: en
source_files_expression: docs/guides/<dir>/source/<file>.md
translation_files_expression: <lang>/<dir>/translations/<file>/product_feature_A.md
Note
In YAML, it's important for the "source_file" to be specified as an absolute path rather than a relative one. This is because BitBucket integration always begins its search from the root directory of the repository. As mentioned earlier, the .yml file can be located anywhere within the repository.
Linking multiple repositories to a project
You can connect multiple repositories to the same project after you link your first repository. To do so, visit your Projects settings > Integrations tab, and click on the Manage link under the BitBucket section to load the integration’s UI. Then click on the ellipsis and select "Link a new repository".
You can switch between the two repositories by clicking on your account name in the top left corner of the integration’s UI.
Whenever you switch between the different repositories, you will see information about resources and the activity log of the selected repository only.
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 associated with the integration).
When a syncing process is initiated, you will see that syncing is in progress from within the integration’s UI. Go to your Project settings > integrations tab under BitBucket and click on the Manage link. Keep in mind that this process may take some time, as it depends on the number and size of the files being synced.
The integration’s page will display an activity log of all syncing operations with BitBucket. These logs allow you to identify any potential issues with particular files that may have either failed to sync or could not be located.
Manual Sync
There is an option to send localized content to BitBucket manually without waiting for a resource to be 100% translated/reviewed/proofread. There is a "Manual Sync" option available on the Projects settings > Integrations > Manage.
A modal will appear requesting 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 set up for the integration.
For example, if you had set up 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 to or above the threshold percentage you set on the modal, thereby creating a commit for each resource for each target language.
Note
If you send less than 100% translated content to BitBucket, the untranslated content will be sent as either empty or containing the source string as the translation. This behavior is contingent on the file format. This functionality is analogous to selecting the "download for use" option in the user interface or the default mode in the GO CLI or API.
To get a more detailed description of how the default translation pull mode behaves for a particular file format, visit the links below, depending on the format you use.
Editing the Project-Bitbucket Link
As your project evolves, you may 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 Manage link under the BitBucket section to load the integration’s UI. Then click on the ellipsis and select Edit Settings.
While the interface used for editing is the same as that used during the initial setup, you will only be able to:
Update the files to be synced in the BitBucket repository by changing the YAML configuration.
Change options on how updates from Transifex are sent back to BitBucket.
Warning
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 also keep in mind that when you change your YAML configuration:
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 opening due to the integration are happening from a BitBucket user called Transifex-localization-platform[bot].
Unlinking a BitBucket repository
If, for any reason, you want to remove the integration, visit your Projects settings > integrations tab and click on the Manage link under the BitBucket section to load the integration’s UI. Then click on the ellipsis and select Unlink. You will be prompted to confirm this action.
Note
The activity log related to the previously connected repository will no longer be available after this action is performed.
Checking the status of the BitBucket integration
Sometimes there are changes happening on the BitBucket side that can affect the BitBucket integration and the synchronization with Transifex.
More specifically, if the configuration file in the BitBucket repository is corrupt or absent or the linked branch is deleted, Transifex and BitBucket will stop exchanging content. The owner of the integration, i.e., the project maintainer or administrator who installed it in a specific project, will receive notifications regarding the integration's health status in two ways:
When viewing the integration’s UI, the status indicator for the connection with the associated BitBucket repository shifts from green to red.
The owner of the integration receives an automated email notification that prompts them to investigate the cause of the problem in the BitBucket integration.
Uninstalling the BitBucket integration
To uninstall the BitBucket integration from your project, follow the steps below:
Go to your project Settings > Integrations > BitBucket > Manage > Elipsis > Unlick
Next, click Unauthorize
Finally, click Revoke access from your project's Integrations page
Continue Reading