Overview
This article will guide you through setting up the new GitLab Connector in Bureau Works. This integration allows you to automatically sync translation files between your GitLab repository and Bureau Works. You'll learn how to connect, configure, and use the YAML config file required to automate your translation workflow.
Index
1. Accessing the GitLab Connector in Bureau Works
First, navigate to the left menu in Bureau Works and select Integrations. You will see the GitLab card available for setup.
Click on Configure in the GitLab card to begin the process.
2. Setting Up the GitLab Integration
Click on Add Configuration and select a Type of Integration (e.g Gitlab, Zendesk or Bitbucket). A window will open asking for the following details to connect your GitLab repository:
Name: Enter a name for this configuration.
Base URL: Use
https://gitlab.comfor public GitLab, or your custom domain for self-hosted GitLab.Access token: You’ll need to generate a Personal Access Token in your GitLab account.
3. Generating a Personal Access Token in GitLab
Click on your profile picture in GitLab and select Preferences.
In the left menu, select Personal access tokens and click Add new token.
Enter a name for your token and check the following permissions (scopes):
read_repositorywrite_repositoryapi
Click Create token and copy the generated token. Make sure to save it securely—you won’t be able to see it again later.
Paste this token into the Access token field in your Bureau Works GitLab configuration.
4. Configuring the Project for Sync
When creating a new sync project with GitLab, you’ll need to fill in the following required fields:
Organizational Unit: Select a unit within the organization.
Contact Person: This person will receive project notifications.
Project Reference: Reference name for this new project.
Source Language: Base language to be translated.
Target Language: Target language in which the translation was made.
Workflows: Necessary steps for your translation (e.g TRANSLATION, REVIEW).
Project path: The full GitLab project path, including group (e.g.,
https://gitlab.com/group/project, the project path would begroup/project)Source branch: The branch name to read source files from (e.g.,
mainormaster).Config path: The path to the YAML config file within your repository (e.g.,
bw-config.yml).Files (optional): A list of specific files to synchronize (e.g.,
README.md,term.json).
5. Setting Up the Connector YAML File
The YAML config file must be created and added to your GitLab repository. It defines:
Source and target languages
Which files to translate
How and where to deliver translated files
Basic structure:
sourceLocale:
key: <source-code-in-repo>
tms: <source-code-in-BW>
locales:
- key: <target-code-in-repo>
tms: <target-code-in-BW>
# ...repeat for other targets
sources:
- defaultOutputPathPattern: "<output-pattern>"
filenameLanguageSeparator: <separator-or-null> # optional
sourceFiles:
- path: <relative/path/to/source-file>
# ...more files
# ...repeat for other groups
6. YAML Configuration Examples
Example 1: Single file, overwrite in place
sourceLocale:
key: en
tms: en_us
locales:
- key: pt-BR
tms: pt_br
sources:
- defaultOutputPathPattern: "{filename}"
sourceFiles:
- path: README.md
Example 2: Multiple files, under i18n/{lang}/ 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 in ja-JP
- path: ui/header.en.yml # becomes header.yml in ja-JP
7. Translation Delivery Flow
The connector reads the YAML file in your repository and validates the configuration.
During sync, source files are read and sent for translation.
After translation is finished, the connector creates a new branch, applies the YAML delivery rules, and opens a Merge Request with the translated files in the specified locations.
8. Frequently Asked Questions (FAQ)
Can I use it with self-hosted GitLab?
Yes! Just use your self-hosted GitLab URL in the Base URL field.
Do I need to renew the token periodically?
The token follows the expiration rules you set in GitLab. Remember to keep track and renew it when needed.
How do I know if the sync worked?
After clicking Sync, check the request status on the screen. If there’s an error, you’ll see a detailed message explaining the issue.