Skip to main content

wxrks - GitLab Connector

Sync files between a GitLab project and wxrks for translation, and get them back via an automatic merge request.

The GitLab connector syncs source files straight out of a GitLab project into wxrks for translation, then delivers the translated files back to GitLab as a merge request. This guide covers creating the connector configuration, generating a GitLab Personal Access Token, setting up the project sync, and writing the YAML config file that tells wxrks which files to translate and where to put the results. It works the same way against GitLab.com or a self-hosted GitLab instance.

💡 Who is this for? This guide is for Account Admins and Project Managers with connector-management permissions for the Organizational Unit you're connecting.

Before you start

  • A GitLab account with access to the project you want to sync, and a Personal Access Token generated from that account (see Generating a Personal Access Token below).

  • The Organizational Unit in wxrks that the resulting project should belong to.

Step 1: Create a GitLab Configuration

Go to Integrations in the left navigation, search for GitLab, and click Configure on its tile.

Integrations page filtered to GitLab, with the Configure button highlighted

In the Add Configuration modal, set:

Field

Description

Type

Select GitLab.

Name

An internal label to tell this configuration apart from others.

Base URL *

Use https://gitlab.com for GitLab.com, or your instance's own domain for self-hosted GitLab.

Access token *

A GitLab Personal Access Token. See Generating a Personal Access Token below.

Add Configuration modal with Type, Name, Base URL, and Access token fields for GitLab

Click Save. The new configuration appears in the Configs list with a Sync button.

Step 2: Generate a Personal Access Token in GitLab

  1. In GitLab, click your profile picture and select Preferences.

GitLab profile menu, Preferences option

  1. In the left menu, select Access tokens and click Add new token.

GitLab Access tokens page, Add new token

  1. Name the token and select these scopes:

    • read_repository

    • write_repository

    • api

GitLab token scopes selection

  1. Click Create token and copy it immediately — GitLab only shows it once.

GitLab token created and copied

  1. Paste the token into the Access token field of your wxrks GitLab configuration.

Step 3: Sync a project (create a project)

Click Sync on your configuration's row. This opens the Create Project form:

Field

Description

Organizational Unit *

The unit the resulting project belongs to.

Contact Person *

Receives notifications about this project.

Project Reference *

A name for the resulting project.

Source Language

If left blank, wxrks uses the source language defined in the config file.

Target Languages

If left blank, wxrks uses the target languages defined in the config file.

Workflows *

The workflow steps this project should follow (e.g. Translation, Review).

Project path *

The full GitLab project path including namespace — for https://gitlab.com/group/project, that's group/project.

Source branch *

The branch wxrks reads source files from (e.g. main).

Config path *

Path to the YAML config file (see below) in the project.

Files

Optional — a comma-separated list of specific files to sync (e.g. README.md, term.json), overriding whatever the config file lists. Leave blank to sync everything the config file lists.

Note that Source Language and Target Languages are the only fields here that aren't required — this differs slightly from wxrks's Bitbucket connector, whose equivalent fields default to the Organizational Unit's languages rather than the config file's.

GitLab Create Project sync form with example values filled in

Force Entry Creation — normally, wxrks skips a file if an identical, already-completed entry exists (same filename, content, source, and target language — see Duplicate handling below). Turn this on to force a new entry to be created anyway.

Click Sync. wxrks creates the project and starts pulling in the files listed in your config; you can track progress in the Requests table that appears on the same page, which refreshes automatically every few seconds. If something goes wrong, that table shows a detailed error message rather than a bare failure.

Step 4: Add the YAML config file to your project

wxrks reads a YAML file — at the Config path you set above — that defines which files to translate, from which source language to which target languages, and where to write the translated files before opening a merge request. It must be committed to the project being synced.

Structure

filenameLanguageSeparator: <separator>  # optional, applies to every group below
sourceLocale:
  key: <source-language-code-in-repo>
  tms: <matching-wxrks-language-code>
locales:
  - key: <target-language-code-in-repo>
    tms: <matching-wxrks-language-code>
  # ...repeat for other target languages
sources:
  - defaultOutputPathPattern: "<output-pattern>"
    filenameLanguageSeparator: <separator-or-omitted>  # optional, overrides the group above for this source group only
    sourceFiles:
      - path: <relative/path/to/source/file>
      # ...more files
  # ...repeat for other groups of files

Field reference

  • sourceLocale.key / locales[].key — the language code as it appears in your repository or filenames (e.g. en, pt-BR).

  • sourceLocale.tms / locales[].tms — the matching wxrks language code (e.g. en_us, pt_br). key and tms together are used for both pulling files in and writing translations back out.

  • defaultOutputPathPattern — where translated files are written, using {lang} or {target} (the target language's key) and {filename} as placeholders. For example:

    • "i18n/{lang}/{filename}" — writes each translation under a per-language subfolder, leaving the original untouched.

    • "{filename}" — overwrites the original file in the project root.

  • filenameLanguageSeparator — set this only if your source filenames already embed a language code (e.g. messages_en.json, separator _) that needs to be stripped when generating the destination filename. Leave it out for plain filenames like README.md. It can be set once at the top level for every group, or overridden per group.

  • sourceFiles — the files to translate in this group, as paths relative to the project root.

Note: the source and target languages set in the YAML file only take effect if you leave Source Language / Target Languages blank in the sync form — a language selected in the form always takes priority.

Examples

File: bw-config.yml

Example 1 — a single file, overwritten in place

sourceLocale:
  key: en
  tms: en_us

locales:
  - key: pt-BR
    tms: pt_br

sources:
  - defaultOutputPathPattern: "{filename}"
    sourceFiles:
      - path: README.md

Example 2 — several files, under per-language folders

sourceLocale:
  key: en
  tms: en_us

locales:
  - key: pt-BR
    tms: pt_br
  - key: es
    tms: es_es

sources:
  - defaultOutputPathPattern: "i18n/{lang}/{filename}"
    sourceFiles:
      - path: README.md
      - path: docs/guide.md

Example 3 — filenames already include the language code

sourceLocale:
  key: en
  tms: en_us

locales:
  - key: ja-JP
    tms: ja_jp

sources:
  - defaultOutputPathPattern: "out/{lang}/{filename}"
    filenameLanguageSeparator: "."
    sourceFiles:
      - path: messages.en.json  # becomes messages.json under out/ja-JP/
      - path: ui/header.en.yml  # becomes header.yml under out/ja-JP/

Important: every filename in sourceFiles must include its extension (e.g. test.json, not test) — without one, wxrks can't sync the file correctly.

After translation

Once translation is complete, wxrks creates a new branch off your source branch, commits the translated files to it in the locations your config file's defaultOutputPathPattern defines, and automatically opens a Merge Request back to your source branch. Review and merge it using GitLab's normal workflow.

Duplicate handling

wxrks skips re-syncing a file if all of the following already match an existing, completed entry:

  • the filename,

  • the file's content (compared by hash), and

  • the source and target language.

This avoids creating duplicate entries or re-processing files that haven't changed. If you genuinely need to re-run translation for a file matching all three, turn on Force Entry Creation in the sync form to skip this check for that sync.

Frequently asked questions

Can I use this with a self-hosted GitLab instance?
Yes — just use your instance's own domain in the Base URL field instead of https://gitlab.com.

Do I need to renew the Personal Access Token?
Only if you set an expiration date on it in GitLab — the token follows whatever expiration rules you configured there, not a rule set by wxrks.

How do I know a sync worked?
Check the Requests table on the Create Project page after clicking Sync — a failed request shows a detailed error message there rather than failing silently.

Related articles

Related Articles
Did this answer your question?