How It Works
The integration with Bitbucket allows you to synchronize repository files directly with the Bureau Works platform. With this connection, you can submit files for translation and receive translated content automatically via Pull Request.
The general workflow is as follows:
Create a Bitbucket Connector Configuration in the Bureau Works platform.
Authenticate via API Token with Bitbucket.
Define repository details (workspace, repository, branch, folder, and files).
Send the selected files to the platform for translation.
Receive the translated files via an automatically created Pull Request in a new branch.
Creating a Connector Configuration
To get started, navigate to the Bitbucket connector and click “Add Configuration”.
Fill out the following fields:
Field | Description |
1 - Type | Select Bitbucket. |
2 - Name | An internal name to identify the configuration. |
3 - Email | The email associated with your Bitbucket account. |
4 - API Token | Access token generated at https://id.atlassian.com/manage-profile/security/api-tokens. This token must be created before setting up the configuration in Bureau Works. |
5 - Language Mapping | Map Bitbucket languages to Bureau Works. Use source=destination format, where the first value is the repo language and the second is in BW. Separate mappings with semicolons (;). Example: en-us=en;cs=cs_cz. |
Click Save to store the configuration.
Configurations:
API Token
The API Token is a secure authentication method that replaces the account password for API calls. It allows the system to access the repository on behalf of the user with controlled permissions.
How to Create and Configure a Bitbucket API Token
Click Create API Token with Scopes.
Set a name and select an expiration date (up to 1 year).
Select the Bitbucket application.
Assign the required permissions, for example:
repository:bitbucket → Read, Write
pullrequests:bitbucket → Read, Write
workspace:bitbucket → Read, Write
project:bitbucket → Read, Write
permissions:bitbucket → Read, Write
user:bitbucket → Read, Write
Click Create to generate the token.
Name step.
Choice of provider.
In Scope Actions select read and write and define the permissions.
Validate the permissions and finish by clicking in Create Token.
Repository Configuration
Once your account is connected, configure the repository parameters for synchronization:
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).
Workspace: Your Bitbucket workspace name (available in the repository URL).
Repository: The repository name.
Branch: The main branch where the files are located (e.g.,
main).Config Path (mandatory): Path to the translation config file in the repository (YAML).
Files (optional): A list of specific files to synchronize (e.g.,
README.md,terms.json).
If no files are specified, all text files located in the folder will be included.
Example Values
Parameter | Example Value |
Workspace |
|
Repository |
|
Branch |
|
Files |
|
Click New Sync.
Define your configuration setup based on the information above and finish by clicking Sync to create the project.
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
Where is it located?
The connector points to the YAML file via the
configPathparameter. The file must be committed to the repository that the connector will synchronize and deliver.
Fields explained
1. sourceLocale
key: code of the language used in the repository (e.g., en, en-US)
tms: code of the language in Bureau Works (e.g., en_us)
2. locales (list)
key: code of the target language in the repository (e.g., pt-BR, es)
tms: code of the target language in BW (e.g., pt_br, es_es)
Important: The sourceLocales and target locales defined in the YAML will only be prioritized if you do not set any language in the UI.
3. sources (list of groups)
defaultOutputPathPattern: how to construct the output paths. Available Tokens:
{lang} or {target} → replaced by the target language key
{filename} → base filename (with the language removed if applicable)
filenameLanguageSeparator (optional per group): separator if the filename already contains the language (e.g., "_" for messages_en.json)
sourceFiles: files to translate, using paths relative to the repository
filenameLanguageSeparator (optional global)
Default separator applied to all groups. Can be overridden per group. When to use:
✅ If your files have a language suffix: messages_en.json, labels_en.yml
❌ If your files do NOT have a suffix: test.txt, README.md (no need to define)
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
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
After the translation process in Bureau Works:
The translated files are committed to a different path than the original files, where the file will be saved without overwriting the original.
A Pull Request (PR) is automatically opened against the main branch.
Important: Each file name must include its extension (e.g., test.json). Using a file name without an extension (e.g., test) will prevent the synchronization from working correctly.
Translations can be reviewed directly in the PR and approved following the standard Bitbucket workflow.
Duplicate File Handling
The system may skip files during synchronization if:
The file name is identical (e.g.,
README.md).The file content is identical (same hash).
The source and target languages are the same.
This behavior prevents duplicate entries and unnecessary reprocessing.
If you need a new processing cycle for the same file, you can manually force a new synchronization by clicking in Force Entry Creation.
