In order to find more information about the differences between Tx CLI client and a direct integration with Bitbucket, you can check the FAQ section here.
To begin you require three basic steps:
Navigate to Organization settings > Manage Integrations and click the "Authorize" link and then the "Authorize the Transifex app" link under the Bitbucket widget. Then you’ll be able to see something like this:
Navigate to your Transifex project of choice and click Settings, then navigate to Integrations tab.
Click the Link Repository in the Bitbucket Integration widget and fillup the required details in the modal that pops up (See images below for each Link step)
When done hit Save & Sync to link your Transifex project to your Bitbucket repository and branch.
Modal options are exactly the same as GitHub options, here for details.
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.
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>".
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
enfor 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 in the sections to follow.
- Synching a Single File:
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
filters: - filter_type: dir file_format: STRINGS source_file_extension: strings source_language: en source_file_dir: locale/DirTest translation_files_expression: 'Translations/<lang>'
- Synching Multiple Files of Different File Types
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>'
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.
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.
As your project evolves, you might end up in situations that 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 synched with the corresponding file(s) in Bitbucket.
Any commits or PRs that are opening due to the integration are happening from a Bitbucket user called Transifex-localization-platform[bot].