Link Transifex with GitHub
In order to find more information about the differences between Tx CLI client and a direct integration with GitHub, you can check the FAQ section here.
Simply point, click and update resources directly from Github with no coding. With the new GitHub Integration you will be able to connect a localization project in Transifex with a specific repository in GitHub using only the Transifex user interface.
To begin you require two basic steps:
Here is a quick video showcasing the two steps.
Choose to link to GitHub
- From the main menu, click the down arrow by your Transifex Organization, then click Organization settings.
- From the Left Hand Side Menu that appears, select Manage Integrations.
- In the Github integration box, click on the Authorize link and then the Install the Transifex app link.
- Select the GitHub Organization you wish to install the Transifex App to.
- Scroll down the page and go to the Repository access section where you can select the Github repositories you want to connect to your TX organization. You have the following 2 options:
- All repositories. This option allows you to connect all current and future repositories to your TX organization. Each repository can be connected to a different project in Transifex.
- Only select repositories. This option allows you to select specific repositories so that only the selected ones can be synced with your TX organization
- Click the Save button.
Connect the GitHub account with your localization organization in Transifex.
- Return back to the Manage Integrations Page in Transifex and click on the Authorize Transifex Link.
- Authenticate to GitHub and choose one or more repositories to make visible in Transifex. Authentication and repository selection on Github should be done by an owner (admin) of the account.
- When you are done with this process, you have authorized the selected GitHub repositories to be able to link to your organization’s localization projects.
Avoid Java Properties files with the GitHub integration
Java Properties files use ISO-8859-1 encoding rather than UTF-8 encoding, which is what most other file formats use. We have identified an issue with this type of encoding and the library that is used to push translation files back to GitHub. Because of this, we cannot guarantee that translation files that are pushed back to GitHub will remain with the correct encoding of ISO-8859-1.
Here is a quick video showcasing these steps.
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 GitHub option along with a button to Link Repository.
Clicking on that button, the GitHub Integration wizard will pop up to manage the setup.
On the first step of the wizard, select the GitHub repository and branch to sync with the project.
Available repositories listed are the ones you authorized when you installed the Transifex app on the Github account you used for the integration. At this point, the GitHub 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). Please check the examples of the “transifex.yml” file below. 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 GitHub repository and branch.
Note: Whenever your config file is updated in your GitHub repository, Transifex is getting notified and automatically a sync process between the 2 systems is triggered.
Clicking the Next button navigates to the final step of the setup, where you will define how the syncing between Transifex and GitHub will happen.
Pulling content from the designated GitHub repository and branch happens automatically upon changes on that branch.
To push localized content from Transifex back to GitHub you have the following options:
Upon 100% translated, reviewed or proofread content.
Push content via a 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 GitHub.
Push content via a commit back to the selected branch.
When you are done with this setup you can click Save & Sync to start syncing content from GitHub to Transifex.
- 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>".
In case your localization process is already in progress, and your projects/resources have already been created in Transifex, you can still use the GitHub integration syncing your existing content stored in Transifex with your files hosted in GitHub. 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 = "directorystructure-filename-extension--<branch name>" where filename is the name of the file stored in GitHub, extension is the extension of the file, directorystructure is the full path of your github directory and <branch name> is the name of the GitHub branch you've selected while setting this integration up.
- Let's assume that the source file with the filename android.xml is stored in GitHub and you have already uploaded it to Transifex.
- Once the TX resource is created, Transifex automatically generates a resource slug of the format: androidxml
- Let's also assume that this file is stored in Github in the locale/i18n directory
- When you sync this resource with GitHub, the system will locate the correct TX resource and then it will change the resource slug from androidxml to locale-i18n-android-xml--master while maintaining the same name (the full path to the file is also included).
- Note: if the sync was done prior to September 28, 2019 then the slug and file name would be as seen in the image below ((the path to the file is not included)):
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 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.
- 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>'
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:
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.txt
- Synching 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-tw
There is an option to send localised content to GitHub manually, without waiting for a resource to be 100% translated or reviewed. There is a "Sync Manually" option available on the Projects settings > Integrations tab in the GitHub card.
By Clicking on "Send To Github" a modal will appear requesting for the threshold localisation percentage that Transifex will check on all your project's resources.
All target languages that are localized above that threshold will be synced with GitHub using the Sync content options you have set up for the integration. For example, if you had set up GitHub 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.
Sending less than 100% translated content to Github 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.
- Android XML
- ChromeJSON (i18N)
- Apple StringsDict
- Github Mark-Down
- Adobe InDesign
- YAML Generic
- YAML Ruby on Rails
Syncing content from GitHub to Transifex happens either upon saving or updating the integration settings on the project level or automatically whenever new content is found on GitHub (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 progress in your Project settings > integrations tab under GitHub. 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 GitHub, 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.
Clicking on the "more" link will provide information on the last sync as seen below:
As your project evolves, you might end up in situations that you want to either extend the files you are syncing from GitHub or change the workflow of pushing localized content back on GitHub. To edit your options visit your Projects settings > integrations tab and click on the ellipsis then Edit Settings.
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 GitHub repository, by changing the YAML configuration.
Change options on how updates from Transifex are sent back to GitHub.
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 GitHub.
Please keep in mind that when you change your YML configuration file in Github:
- - 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
Any commits or PRs that are opening due to the integration are happening from a GitHub user called Transifex-localization-platform[bot].