You can effortlessly update resources on GitLab without coding just by pointing and clicking. Through the Transifex GitLab integration, you can link a localization project in Transifex to a designated GitLab repository using only the Transifex user interface.
Installing the Gitlab Integration in a Specific Project
To install the standalone integration that connects Transifex and GitLab, you need to perform the following steps:
Go to your project Settings > Integrations > GitLab > Install
You will be redirected to the integration’s authorization page, where it's necessary to give permission for the integration to perform modifications in Transifex for you.
Then, you will have two options: link a GitLab Account from gitlab.com or host a self-hosted version from a private URL.
Link a GitLab Account from gitlab.com
To link a GitLab account from gitlab.com, select the Authorize Via button and choose GitLab Account.
Log into your GitLab account (if you still need to). Finally, click the Authorize button to complete.
Link your self-hosted version from a private URL
If you have your own self-hosted version of GitLab, select the Authorize Via button and choose the Access token option.
Then, add your URL where the self-hosted version resides, add your access token, and click Submit.
Once authorized, you will be redirected back to the GitLab integration’s UI. At this point, you can authorize the GitLab integration to access your GitLab account.
Upon clicking Authorize, you will see all accounts for which you have to write permissions (i.e., Developer role or above):
Once you are done, select the GitLab account you would like to connect with your project. You are now ready to link a repository.
📝 Important Note: Your privacy and data security are our utmost priority.
File Handling: Rest assured that we will never read, write, or delete any files beyond what is specified in the YAML file. Our scanning process only aims to find matching files based on the provided YAML configuration.
Pull Request Policy: We respect the integrity of the Pull Request system. We will never close any Pull Request not initiated by our integration.
Linking a Specific Project with a GitLab Repository
Clicking on the Link Repository button, the GitLab Integration wizard will pop up to manage the setup.
Select your Repository
On the wizard's first step, select the GitLab repository and branch to sync with the project. The available repositories listed are under the GitLab accounts you authorized during the previous step. At this point, the GitLab integration works on top of a single branch.
For the Multi-branching feature, you can find more information here.
Select files
When you finish this step, click Next to set up the repository files related to localization.
There are two ways to select what GitLab files will be synced with your Transifex project:
The first is through a YML config file called “transifex.yml” (but you can name it as you wish). This file will be hosted in your GitLab 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 wizard's next step, ensure 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. You can click the Next button to connect your Transifex project and your GitLab repository and branch when it's complete.
📝 Note: Whenever your config file is updated in your GitLab 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, including any translations obtained from GitLab. These resources will be identified by a unique slug. The GitLab repository and branch path will be added as categories for these resources.
Regarding existing resources that have already been synchronized with GitLab, if translations are detected in your GitLab repository, and no translations for that language exist in Transifex, these newly detected translation files will be sent to Transifex.
Sync content
By selecting the Next button, you will be directed to the last step of the configuration, where you will establish the mechanism for synchronization between Transifex and GitLab.
Pulling content from your repository to Transifex.
Whenever any changes are made to the designated branch of a GitLab repository, the process of pulling content from that branch happens automatically. This means that any new code or updates pushed to the repository will be automatically incorporated into the project. This automated process saves significant time and effort, as it eliminates the need for manual updates or synchronization of the code.
Pushing content from Transifex to your repository.
You can decide when and how your localized content is pushed to your repository.
When to push your localized content to GitLab depends on the progress of your localization process. You can decide when to push your translated content to your repo; you have the following options to set this up:
100% translated
100% reviewed
100% proofread
custom
Below, you'll read more about these options.
When a target language reaches 100% of the translation work done.
When you choose to push your content to your repository using this option, it means that Transifex will only push a file's translations once this file has all its strings translated in a specific target language; it will only push the translations of this language to the repository; and it'll not push the translations of target languages that have less than 100% of completion.
For example, if you have a file with the following translation progress, only the translations of Afrikaans(af) and Greek(el) will be sent to your repository, and the Spanish(es) translations will be ignored.
When a target language reaches 100% of reviewed strings.
When you choose to push your content to your repository using this option, it means that Transifex will only push a file's translations once this file has all its strings reviewed in a specific target language; it will only push the translations of this language to the repository; and it'll not push the translations of target languages that have less than 100% of reviewed strings.
For example, if you have a file with the following translation progress, only the translations of Afrikaans(af) will be sent to your repository, and the Spanish(es) and Greek(el) translations will be ignored.
When a target language reaches 100% of proofread strings.
When you choose to push your content to your repository using this option, it means that Transifex will only push a file's translations once this file has all its strings proofread in a specific target language; it will only push the translations of this language to the repository; and it'll not push the translations of target languages that have less than 100% of proofread strings.
For example, if you have a file with the following translation progress, only the translations of Greek(el) will be sent to your repository, and the Spanish(es) and Afrikaans(af) translations will be ignored.
Push content according to a Custom threshold (<100%)
If you need your translations to reach GitLab 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).
📝Note: if a language is already translated/reviewed/proofread and translations are updated in Transifex, the updated translations will automatically be sent to your repo.
For example, if you have a file with the following translation progress and define the custom threshold to 60% translated, only the translations of Greek(el) and Afrikaans(af) will be sent to your repository, and the Spanish(es) translations will be ignored.
You can also define how your translation content reaches your repository; below, you'll find the option you have to set up the way the translations in Transifex hit your repository. You can choose between:
Create a Pull Request
Commit directly
Below, you'll find more information about these options:
Create a Pull Request
This will create a new branch with the localized content and open a PR on the branch that you can later merge directly from GitLab. However, if an open PR already exists containing previous translations, it will be updated with the latest ones.
Content grouping
You can group PRs, particularly when dealing with numerous target languages in your project and resources requiring localization. The following grouping options are available:No grouping - This creates separate PRs for each resource and language combination.
By resource - The PR will contain translations in all target languages for a single resource.
By language - The PR will contain translations in a specific language for all resources.
All resources and languages - This creates a single PR that includes translations for all resources and all target languages.
Commit directly for branches associated with the multi-branch feature
Enabling this option allows you to customize how translation updates are pushed to branches associated with the multi-branch feature while keeping the PR option for your default branch. Please note that this option is available exclusively when the Multi-branching option is enabled.
Commit directly. Commit changes directly to the selected branch.
📝Things to note when using Pull Requests
Suppose the translation or review percentage falls below the set threshold in Transifex, and a PR has already been opened in your repository. In that case, we'll automatically close the PR to ensure no outdated translations remain pending for your review.
If a PR is created based on the condition that x% of the language is translated and the setting is later updated to y% for review or proofreading, we'll close the existing PR and open a new one once the new conditions are met. This ensures that your repository always has the latest and most accurate translations.
Additionally, in this tab of the GitLab integration wizard, you'll find some optional settings. To learn more about them, visit the section Optional Settings in the Sync content tab.
Once you complete the setup, click "Save & Sync" to initiate the synchronization process between GitLab and Transifex.
⚠️ Warning: 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.
Optional settings in the Sync content tab
When configuring the link settings between your Transifex project and your GitLab repository, you'll come across a section called "Sync Content".
In this section, you'll find various alternative features that can be used to set up the way your translated content reaches your repository:
Add a prefix to the commit message.
Add a prefix in the Pull Request title.
Receive updates for source files.
Add an interval between commits.
In this article, you'll find the specifications of such features.
Add a Prefix Your Commit Message
If you have configured GitLab Actions in your repository and want to exclude commits made by the Transifex GitLab integration from workflow runs, you can add a prefix to the commit message. This will also improve readability in your workflow.
For example, if I add the prefix "TRANSLATION-UPDATE" and save this setting update:
The commits sent to GitLab will show this prefix.
Add a prefix in the Pull Request title.
If you have configured GitLab Actions in your repository and want to admit only certain Pull Requests in your workflow, you can add a prefix to the Pull Requests title; this will also improve readability in your workflow.
For example, if I add the prefix "NEW-PR-TITLE" and save this setting update:
The Pull Requests sent to GitLab will show this prefix.
Receive updates for source files.
Enabling the feature Receive updates for source files means that you can sync any changes you make to your source file in Transifex with your repository without any manual intervention. This can save you a considerable amount of time and effort. Additionally, it ensures that the most up-to-date version of your project is always available to your users.
It's important to note that not all file formats support automatic updates. Therefore, it's advisable to consult the article on Updating Content to obtain more information about which file formats can have their source updated in Transifex.
Add an interval between commits.
If you want to avoid having many commits of the same translation file flooding your repository for every single update of translations, you can set a time interval to group those updates in one commit.
By setting a time interval in minutes (up to a maximum of 60 minutes), you can control how often translation updates get pushed to your repository so that you can manage your translation changes in your repository more effectively.
For example, let's say that you've set the commit interval to 10 minutes. Within those 10 minutes, you make several translation edits in a resource file. Instead of individual commits for each change, you'll receive a single commit after the 10-minute interval expires, including all the latest updates. If you continue to edit the same translations, a new commit will be generated after another 10 minutes, grouping all changes made during that time.
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 dir for directory, file, and dynamic.
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 double or single quotes.
source_file_dir: Only used for the directory (dir) filter_type. Works the same as source_file.
source_files_expression: Only used for the dynamic 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. Please take a look at 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 your translation files' file/directory structure. 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.
settings:
language_mapping:
REMOTE_CODE: LOCAL_CODE
The REMOTE_CODE is the language code supported by Transifex. And the LOCAL_CODE is your language code.
📝 Mapping locales will only impact the filenames of the translation files, aligning file naming conventions with your selected locale mappings.
The configuration follows a YAML syntax, and users can define a list of individual files or use regular expressions to match multiple files simultaneously. Illustrated examples can be found below:
pr_branch_name: If you want to specify the name used for a PR when pushing translations back to GitLab, you can use this parameter under the settings like in the following example. Please note that <br_unique_id> is a string hash 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 locations. Each entry begins with "- filter_type: ".
Check the section More Examples of YAML Configurations for samples.
More Examples of YAML Configurations
Syncing a Single File
filters:
- filter_type: file
file_format: PO
source_file: locale/example.po
source_language: en
translation_files_expression: 'Translations/<lang>/'
Syncing 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>'
⚠️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 examples can illustrate this.
Example 1
Example 1
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'
Example 2
Example 2
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 Multiple Files, Excluding Specific Paths/Localization Files
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
Syncing Files With a Specific Branch Name and With Language Mapping
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
Examples of the dynamic Filter Type (ignore_dirs, ignore_files are also supported in this filter type)
Example 1:
git:
filters:
- filter_type: dynamic
file_format: PO
source_language: en
source_files_expression: folder/<file>.po
translation_files_expression: 'locale/<lang>/<file>.po'
Examples of possible source file matches:
Example 2:
git:
filters:
- filter_type: dynamic
file_format: PO
source_language: en
source_files_expression: <dir>/<file>.po
translation_files_expression: '<dir>/<lang>/<file>.po'
Examples of possible matches:
Other examples of filter_type: dynamic
Example 1
Example 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
Example 2
Example 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 essential for the "source_file" to be specified as an absolute path rather than a relative one. The GitLab integration always begins its search from the repository's root directory. As mentioned, the .yml file can be located anywhere within the repository.
💡Tip
Looking for more help? Get support from our Transifex Community Forum!
Find answers or post to get help from Transifex Support and our Community.