Connect a Transifex project to a GitLab repository so that source files sync to Transifex automatically and translations go back to GitLab as commits or merge requests. You set up the connection in Transifex. In your repository, you only add a YAML configuration file that lists the files to sync (see YAML configuration parameters).

🔒 Available on: All plans. Role required: Organization Administrator, Project Maintainer

Install the GitLab integration in a project

In your project, go to Settings > Integrations > GitLab and click Install.
On the authorization page, choose your Project and click Allow. This lets the GitLab integration read your project, create and update resources, and upload and download source files and translations.
Connect GitLab with a GitLab account on gitlab.com, or with an access token for a self-hosted GitLab instance.

Link a GitLab account from gitlab.com

Click Authorize via and choose GitLab account.
Sign in to GitLab if asked, then click Authorize.

Link a self-hosted GitLab instance

Click Authorize via and choose Access token.
Enter the URL of your GitLab instance and an Access Token, then click Submit.

📝 Note: The integration supports GitLab versions later than 9.0, with personal, project, or group access tokens. GitLab's documentation explains how to create each one.

Choose the GitLab account

After you authorize, you return to the GitLab integration page. Click Authorize to let the integration access your GitLab account.

GitLab Integration page with the Authorize button highlighted

The integration then lists every group and user account where you have write access (the Developer role or higher). Select the account you want to connect to this project.

GitLab Authorization page listing a group and a user account to choose from

The integration page now shows the account as Authorized, and you can link a repository.

GitLab Integration page showing an authorized account and the Link Repository button highlighted

📝 Note: The integration only reads, writes or deletes the files that match your YAML configuration. It never closes a merge request that it didn't open.

Link a project to a GitLab repository

Click Link Repository to open the setup wizard. It has three steps: Select repo, Select files, and Sync content.

Select your repository

Select the GitLab repository and the branch to sync with this project. The list shows the repositories of the GitLab accounts you authorized.

Link Repository wizard on the Select repo step, with a repository, the main branch and the Multi-branching checkbox

The integration syncs one branch. To track more branches, select Multi-branching. See Working with GitHub/Bitbucket/GitLab/Azure Repos branches.

You can link more repositories to the same project later. See GitLab: Advanced settings.

📝 Note: If your workspace has more than 100 repositories, the repository list becomes a text field. Type the repository's slug in the format account/repository_slug.

Select files

Click Next to choose the files to sync. You describe them in a YAML configuration, in one of two ways:

Add a path to your YAML configuration file: add a file such as transifex.yml to your repository (any name works). By default, the integration looks for it in the root of the branch you selected, but it can be in any folder. Make sure the file is in the repository, enter its path, and click Apply to preview it.
Paste your YAML configuration: paste the configuration into the text box. The wizard checks it as you type.

For the settings you can use, see YAML configuration parameters and More examples of YAML configurations.

Click Test configuration to see which files in the repository match your configuration. When the result looks right, click Next.

📝 Note: When the configuration file changes, in the repository or in the wizard, Transifex syncs with GitLab automatically.

New files in the configuration become new resources in Transifex, together with any translations found in GitLab. The repository and branch path are added as categories on these resources.
For resources that are already synced, translation files found in GitLab are sent to Transifex only for languages that have no translations in Transifex yet.

Sync content

In the last step, choose how content moves between GitLab and Transifex.

Sync content step showing the Create a Pull Request and Commit directly options and the optional settings

Pull content from your repository to Transifex

Transifex pulls content automatically. When the selected branch changes in GitLab, Transifex imports the changes into your project.

Push content from Transifex to your repository

Under When would you like Transifex to push content?, choose when a language's translations of a resource go to GitLab:

100% translated: when all strings of the resource are translated in that language.
100% reviewed: when all strings are reviewed in that language.
100% proofread: when all strings are proofread in that language.
Custom: when a percentage you set is reached. Enter the percentage and choose translated, reviewed or proofread.

Languages below the threshold aren't pushed. The integration makes one commit per language when a resource first reaches the threshold, and again for every later update.

For example, take a resource where Afrikaans and Greek are 100% translated and Spanish is 50% translated:

Push option	Pushed	Not pushed
100% translated	Afrikaans, Greek	Spanish
Custom: 60% translated	Afrikaans, Greek	Spanish
100% reviewed, if only Afrikaans is fully reviewed	Afrikaans	Greek, Spanish
100% proofread, if only Greek is fully proofread	Greek	Afrikaans, Spanish

📝 Note: Once a language has reached the threshold, Transifex also pushes later updates to its translations automatically.

Choose how translations reach GitLab

⚠️ Warning: If the branch is protected, Transifex can't commit to it directly. Remove the protection (see GitLab's protected branches documentation) or choose Create a Pull Request.

Under How would you like Transifex to push translations to GitLab?, choose:

Create a Pull Request: Transifex creates a branch with the translations and opens a merge request from it, which you review and merge in GitLab. (The Transifex settings use the term pull request; GitLab calls it a merge request.) If a merge request with earlier translations is still open, Transifex updates it instead.
Under Group content in your PRs, choose how to group translations:
- No grouping: one merge request per resource and language.
- By resource: one merge request per resource, with all its target languages.
- By language: one merge request per language, with all resources.
- All resources and languages: a single merge request for everything.
With Multi-branching on, you can also select Commit directly for branches associated with the multi-branch feature. Transifex then opens merge requests for your default branch and commits directly to the other tracked branches.
Commit directly: Transifex commits the translations directly to the selected branch.

📝 Note: Transifex manages the merge requests it opens:

If a language falls below the threshold while its merge request is open, Transifex closes the merge request, so outdated translations don't wait for review.
If you change the threshold, for example from translated to reviewed, Transifex closes the open merge request and opens a new one when the new threshold is reached.

This step also has optional settings. When you're done, click Save & Sync to start syncing.

Optional settings in the Sync content step

The Sync content step has four optional settings for how translations reach your repository. You can turn them on when you link the repository, or later in the link settings.

Sync content step with the four optional settings highlighted

Add a prefix to the commit message

Select Add a prefix to the commit message and enter a prefix of up to 128 characters. It applies to direct commits and to commits in merge requests. A prefix makes Transifex commits easy to spot, and lets you exclude them from your GitLab CI/CD pipelines.

For example, with the prefix TRANSLATION-UPDATE:

Add a prefix to the commit message selected, with TRANSLATION-UPDATE entered

Commits from Transifex then start with that prefix:

GitLab commit list with a commit titled TRANSLATION-UPDATE Translate source/test.txt in fr

Add a prefix to the Pull Request title

Select Add a prefix to the Pull Request title and enter a prefix of up to 128 characters. Use it when your repository has naming rules for merge requests, or to filter Transifex merge requests in your CI/CD pipelines.

For example, with the prefix NEW-PR-TITLE:

Add a prefix to the Pull Request title selected, with NEW-PR-TITLE entered

Merge requests from Transifex then start with that prefix:

GitLab merge requests list with a merge request titled NEW-PR-TITLE Updates for file source/test.txt in fr

Receive updates for source files

Select Receive updates for source files to send changes you make to source files in Transifex back to your repository.

Not every file format supports source edits in Transifex. See Updating your source content for the formats that do.

Add an interval between commits

Select Add an interval between commits and enter a number of minutes, up to 60. Transifex then groups translation updates into one commit per interval, instead of committing every change.

For example, with a 10-minute interval, all the edits you make to a resource within 10 minutes arrive as one commit when the interval ends. Edits after that go into the next commit, 10 minutes later.

📝 Note: Each commit covers one resource in one language. If you edit translations in two languages of the same resource, GitLab receives two separate commits, one per language. If you edit two resources in the same language, it also receives two commits, one per resource.

YAML configuration parameters

The YAML configuration starts with a top-level git: key. Everything else goes under it: a filters: key with one or more filters, and optionally a settings: key. Each filter starts with - filter_type: and describes one set of source files and where their translations go. Add a filter for each file type or location.

The wizard's Select files step doesn't show the git: line, so configurations shown there start at filters:.

Parameter	Used with	What it does
`git`	Top level	Required. Holds `filters` and `settings`.
`filter_type`	All filters	`file` for one source file, `dir` for all files with one extension in a directory, or `dynamic` for files that match a pattern.
`file_format`	All filters	The format of the resources, for example `PO`. Each file format page gives its `i18n_type`.
`source_language`	All filters	Your project's source language, for example `en`.
`source_file`	`file`	The path to the source file.
`source_file_dir`	`dir`	The directory that holds the source files.
`source_file_extension`	`dir`	The extension of the source files, for example `strings`.
`source_files_expression`	`dynamic`	A pattern that matches the source files, using `<file>` and optionally `<dir>`.
`translation_files_expression`	All filters	Where the translation files are. It must contain `<lang>`, which Transifex replaces with each target language code, for example `'/translations/po/<lang>.po'`.
`mode`	All filters (optional)	The download mode for translation files. Your file format's page lists the modes it supports.
`ignore_dirs`	`dir`, `dynamic` (optional)	Directories to skip.
`ignore_files`	`dir`, `dynamic` (optional)	Files to skip.

Write every path from the root of the repository, starting with a slash, for example /locale/example.po. The integration always starts its search at the root, wherever the configuration file is. Don't put quotes around source paths. Put single quotes around translation_files_expression.

📝 Note: mode doesn't work for XCSTRINGS files.

Settings

Two optional settings go under settings:, inside git::

language_mapping: maps Transifex language codes to the codes your repository uses, if they differ from the ISO codes (ISO 639-1, ISO 639-2 or ISO 639-3). Each line maps one code. The mapping only changes the file names of translation files.
```
git:
  settings:
    language_mapping:
      <transifex_code>: <repository_code>
```
pr_branch_name: the name of the branch Transifex creates for merge requests. <br_unique_id> is replaced with a unique ID that Transifex generates.

See Sync files with a branch name and language mapping for both settings in one configuration.

More examples of YAML configurations

Sync a single file

git:
  filters:
  - filter_type: file
    file_format: PO
    source_file: /locale/example.po
    source_language: en
    translation_files_expression: '/Translations/<lang>/example.po'

Sync all files of one type in a directory

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>'

Sync a single file with a specific download mode

git:
  filters:
  - filter_type: file
    file_format: YML
    source_language: en
    source_file: /test.yml
    translation_files_expression: '/Translations/target_<lang>.yml'
    mode: onlytranslated

📝 Note: If two file filters cover source and translation files in the same directory, put the more specific filter first, as in these examples.

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

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>'

Sync files in a directory and skip some paths

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.json
      - /localization_project/path1/example4.json

Sync files with a branch name and 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

Sync files that match a pattern

The dynamic filter type matches source files with a pattern. <file> stands for a file name, and <dir> for a directory path of one or more levels. ignore_dirs and ignore_files work with this filter type too.

Example 1: files in one folder

git:
  filters:
  - filter_type: dynamic
    file_format: PO
    source_language: en
    source_files_expression: /folder/<file>.po
    translation_files_expression: '/locale/<lang>/<file>.po'

With target languages Greek (el) and German (de), this matches:

Source file	Translation files
`folder/foo.po`	`locale/el/foo.po`, `locale/de/foo.po`
`folder/bar.po`	`locale/el/bar.po`, `locale/de/bar.po`

Example 2: files in any directory

git:
  filters:
  - filter_type: dynamic
    file_format: PO
    source_language: en
    source_files_expression: /<dir>/<file>.po
    translation_files_expression: '/<dir>/<lang>/<file>.po'

With the same target languages, this matches:

Source file	Translation files
`folder/foo.po`	`folder/el/foo.po`, `folder/de/foo.po`
`f1/f2/f3/foo.po`	`f1/f2/f3/el/foo.po`, `f1/f2/f3/de/foo.po`

More pattern examples