Skip to main content

wxrks - Bitbucket Connector

Updated yesterday

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:

  1. Create a Bitbucket Connector Configuration in the wxrks platform.

  2. Authenticate to Bitbucket via API Token.

  3. Define the repository details (workspace, repository, branch, config path, and files).

  4. Send the selected files to the platform for translation.

  5. Receive the translated files via a Pull Request automatically created 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.

Important: The Email and API Token function as a strict, indivisible credential pair for Atlassian's Basic Authentication. The email provided must exactly match the account used to generate the token, as the connector will inherit this specific user's exact access levels

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

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens.

  2. Click Create API Token with Scopes.

  3. Set a name and select an expiration date (up to 1 year).

  4. Select the Bitbucket application.

  5. Assign the required permissions, for example:

    • repository:bitbucket → Read, Write

    • pullrequest:bitbucket → Read, Write

  6. Click Create to generate the token.

Follow these steps (summary):

  1. Name step.
    ​

  2. Choice of provider.
    ​

  3. In Select Actions select read and write and define the permissions.
    ​


    ​

  4. 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 (mandatory): Select a unit within the organization.

  • Contact Person (mandatory): This person will receive project notifications.

  • Project Reference (mandatory): Reference name for this new project.

  • Source Language (mandatory): iBase language to be translated.

  • Target Language (mandatory): Target language in which the translation was made.

  • Workflows (mandatory): Necessary steps for your translation (e.g TRANSLATION, REVIEW).

  • Workspace (mandatory): Your Bitbucket workspace name (available in the repository URL).

  • Repository (mandatory):The repository name (available in the repository URL).

  • Branch (mandatory): 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 (opcional): A list of specific files to synchronize (e.g., README.md, terms.json).

Example Values

Parameter

Example Value

Workspace

my-company

Repository

integration

Branch

main

Files

messages.json, README.md

Click New Sync.


Define your configuration setup based on the information above and finish by clicking Sync to create the project.


​Force entry creation option: Enable this option to force the creation of a new entry, even if an identical one already exists. This only applies to entries with the status COMPLETED. When enabled, duplicate checks will be ignored.

Setting Up the Connector YAML File

The YAML config file must be created and added to your Bitbucket repository. It defines:

  • Which files to translate

  • From which source language to which target languages

  • Where and how to write the translated files before opening a Pull Request

Where is it located?

  • The connector points to the YAML file via the configPath parameter. The file must be committed to the repository that the connector will synchronize and deliver.

Mandatory structure

filenameLanguageSeparator: <separator>  # opcional global
sourceLocale:
  key: <source-code-in-repo>
  tms: <source-code-in-BW>
locales:
  - key: <destination-code-in-repo>
    Tms: <destination-code-in-BW>
  # ...repeat for other destinations.
sources:
  - defaultOutputPathPattern: "<output-pattern>"
    filenameLanguageSeparator: <separator-or-null>  # optional per group
    sourceFiles:
      - path: <relative/path/to/source/file>
      # ...more files
  # ...repeat for other groups


Explanation of the fields

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

  • 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

  • defaultOutputPathPattern: how to construct the output paths. Available Tokens:

    • {lang} ou {target} → replaced by the target language key

    • {filename} → base filename (with the language removed if applicable)

    • Examples:

      • defaultOutputPathPattern: "locales/{lang}/{filename}". Thus, a folder called locales/ is created with subfolders for each language, and the translated files are saved there without replacing the originals.

      • defaultOutputPathPattern: "{filename}". It will overwrite the original file located in the repository's root directory.

      • defaultOutputPathPattern: "path/{filename}". It will overwrite the original file located in the repository folder.

      • defaultOutputPathPattern: "{sourceFilePath}". It will overwrite the original file, keeping the path to the file and locating it wherever it is.

    • 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)

Mapping rules:

  • key ↔ tms is used for both synchronization and delivery

  • Output paths use the destination key (repository ID)

  • If the source filename includes a language code and filenameLanguageSeparator is set, this part is removed when generating the destination filename

YAML Examples

File: bw-config.yml
​

Example 1: A single file, overwriting in the same 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, in folders i18n/{lang}/

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: File names 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 messages.yml inja-JP

After translation at Bureau Works

  • The translated files are committed to a different path than the original, without overwriting the original files.

  • A Pull Request (PR) is automatically opened against the main branch.

Important: Each filename must include its extension (e.g., test.json). Using a name without an extension (e.g., test) will prevent synchronization from working correctly.

Translations can be reviewed directly in PR and approved following Bitbucket's standard workflow.

Handling duplicate files

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 force a new synchronization by clicking Force Entry Creation.

Related Articles
wxrks TMill
GitHub Connector Overview
wxrks - Eloqua Connector
wxrks - GitHub Connector
wxrks - Gitlab Connector
Did this answer your question?