You can effortlessly update resources on GitLab without coding by just pointing and clicking. Through Transifex GitLab integration, you can link a localization project in Transifex to a designated GitLab repository using only the Transifex user interface.
📝 Note: Currently, GitLab integration does not support self-hosted GitLab instances.
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:
You will be redirected to the integration’s authorization page, where:
Once you click Authorize, 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):
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.
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.
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.
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 the designated GitLab repository and branch happens automatically upon changes on that branch.
To push localized content from Transifex back to GitLab, you have the following options:
Push translations to GitLab when a language becomes:
100% translated
100% reviewed
100% proofread
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).
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 GitLab:
"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.
Prefix Your Commit Message
If you have GitLab CI/CD configured in your repository and wish to exclude the Pull Requests or commits made by the Transifex GitLab 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 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.
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.
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 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
git:
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
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>'
⚠️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
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'
Example 2
Example 2
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>'
Syncing 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
Syncing 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-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.