Table of Content
You can effortlessly update resources on GitHub without coding by just pointing and clicking. Through Transifex GitHub integration, you can link a localization project in Transifex to a designated GitHub repository using only the Transifex user interface.
Tip
Use our traditional GitHub integration tools described here to communicate with GitHub Enterprise. In this manner, access is not given to an external service for something so important internally.
Installing the GitHub integration in a specific project
To install the standalone integration that connects Transifex and GitHub, you need to perform the following steps:
Go to your project Settings > Integrations > GitHub > 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 GitHub account. To do this, select the Authorize button and log into your GitHub account (if you haven't already done so).
Available installations will be listed next. To configure your GitHub applications, visit your GitHub settings page using the link available on the page below:
and click Configure once you are redirected to your GitHub account.
Next, select where you want to install the Transifex integration and select one or multiple repositories to be accessible in Transifex. The owner (admin) of the account must perform the authentication and repository selection on GitHub. You can choose from the following two alternatives:
All repositories. With this option, you can link all present and upcoming repositories to your TX project. You have the option to link each repository to a different project in Transifex.
Only select repositories. With this option, you can select specific repositories to be synced with your TX project(s).
Once you click Install, you will be redirected back to the GitHub integration’s UI. At this point, you can authorize the GitHub integration to access your GitHub account.
Upon clicking Authorize, you will see the installation you executed in the previous steps. In case you installed multiple apps, they will all be listed as shown below:
Select the GitHub account you would like to connect with your project. You are now ready to link a repository.
Linking a specific project with a GitHub repository
Clicking on the Link Repository 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. The 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.
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 GitHub 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 GitHub 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 GitHub repository and branch.
Note
Whenever your config file is updated in your GitHub 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 GitHub. These resources will be identified by a unique slug. The GitHub repository and branch path will be added as categories for these resources.
Regarding existing resources that have already been synchronized with GitHub, if translations are detected in your GitHub 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, where you will establish the mechanism through which the synchronization between Transifex and GitHub will occur.
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:
Push translations to GitHub when a language becomes:
100% translated or
100% reviewed or
100% proofread or
Custom threshold (<100%) If you need your translations to reach GitHub faster without waiting for languages to be fully completed, you can set a less than 100% custom threshold and select the desired translation status (translated, reviewed, proofread).
Additionally, if a language is already translated/reviewed/proofread and translations are updated in Transifex, the updated translations will automatically be sent to your repo.
Push translations to GitHub via:
Pull Request on that branch 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.
Update existing Pull Request. Select this option if you want to prevent frequent opening and closing of Pull Requests in your repository as translation progresses.
Commit back to the selected branch.
Prefix Your Commit Message
If you have GitHub Actions configured in your repository and wish to exclude the Pull Requests or commits made by the Transifex GitHub integration from the workflow runs, you may add a prefix to the commit message. This will also help you to enhance readability in your workflow.
Once you complete the setup, click "Save & Sync" to initiate the synchronization process between GitHub and 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 GitHub
Suppose your localization process is ongoing, and your projects/resources have been established in Transifex. In that case, you can still leverage the GitHub integration to synchronize the content already present in Transifex with the files residing in GitHub. All you need to do is execute the following steps:
Locate the TX resources in your selected GitHub repository and branch.
Note the path of each resource in the GitHub repository,
Keep the following details separately:
Repository name, e.g., transifex/GitHub-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:
github#{full_repo_name}#{branch_name}#{source_file_path}e.g.
github#transifex/GitHub-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
filefilter_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_expression: Only used for the
dynamicfilter_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 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:
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 files 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 GitHub 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.
Manually Triggering The Integration
There is an option to send localized content to GitHub 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 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.
Note
If you send less than 100% translated content to GitHub, 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.
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 GitHub 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.
Syncing content from GitHub
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 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 GitHub 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 GitHub. These logs allow you to identify any potential issues with particular files that may have either failed to sync or could not be located.
Editing the Project-GitHub link
As your project evolves, you may end up in situations where 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 Manage link under the GitHub 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 GitHub repository by changing the YAML configuration.
Change options on how updates from Transifex are sent back to GitHub.
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 GitHub.
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 GitHub
Any commits or PRs opening due to the integration are happening from a GitHub user called Transifex-localization-platform[bot].
Unlinking a GitHub 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 GitHub 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 GitHub integration
Sometimes there are changes happening on the GitHub side that can affect the GitHub integration and the synchronization with Transifex.
More specifically, if the configuration file in the GitHub repository is corrupt or absent or the linked branch is deleted, Transifex and GitHub 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 GitHub 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 GitHub integration.
Uninstalling the GitHub integration
To uninstall the GitHub integration from your project, follow the steps below:
Go to your project Settings > Integrations > GitHub > Manage > Elipsis > Unlick
Next, click Unauthorize
Finally, click Revoke access from your project's Integrations page