The Bitbucket connector syncs source files straight out of a Bitbucket repository into wxrks for translation, then delivers the translated files back to Bitbucket as a pull request. This guide covers creating the connector configuration, authenticating with an Atlassian API token, setting up the repository sync, and writing the YAML config file that tells wxrks which files to translate and where to put the results.

💡 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 Bitbucket account with access to the repository you want to sync, and an email address + API Token pair generated from that account (see API Token below).
The Organizational Unit in wxrks that the resulting project should belong to.

How It Works

The general workflow is:

Create a Bitbucket Configuration in wxrks and authenticate with an Atlassian API Token.
Tell wxrks which repository, branch, and files to sync.
wxrks pulls the selected files in and sends them for translation.
Once translated, wxrks commits the results to a new branch and opens a Pull Request back to your main branch automatically.

Diagram of the Bitbucket sync and delivery workflow

Step 1: Create a Bitbucket Configuration

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

Integrations page filtered to Bitbucket, with the Configure button highlighted

In the Add Configuration modal, set:

Field	Description
Type	Select Bitbucket.
Name	An internal label to tell this configuration apart from others.
Email *	The email address of the Bitbucket account the API Token belongs to.
API Token *	An Atlassian API Token generated from that same account. See API Token below.

Important: Email and API Token are a matched pair for Atlassian's Basic Authentication — the email must belong to the same account the token was generated from, since the connector inherits that account's exact repository access.

Add Configuration modal with Type, Name, Email, and API Token fields for Bitbucket

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

Configs list showing the new Bitbucket configuration with its Sync button highlighted

API Token

An API Token replaces your Bitbucket account password for API calls, letting wxrks access the repository on your behalf with the permissions you grant it.

How to create a Bitbucket API Token

Go to id.atlassian.com/manage-profile/security/api-tokens.
Click Create API token with scopes.
Give it a name and an expiration date (up to 1 year).
Select the Bitbucket app.
Grant, at minimum:
- repository:bitbucket — Read, Write
- pullrequest:bitbucket — Read, Write
Click Create and copy the token — Atlassian only shows it once.

Atlassian API token creation, scopes summary

Atlassian API token creation, choice of provider

Atlassian API token creation, read/write permissions step

Atlassian API token creation, final Create Token step

Step 2: Sync a repository (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 Organizational Unit's default language.
Target Languages	If left blank, wxrks uses the Organizational Unit's default target languages.
Workflows *	The workflow steps this project should follow (e.g. Translation, Review).
Workspace *	Your Bitbucket workspace ID, visible in the repository URL.
Repository *	The repository name, also visible in the repository URL.
Branch *	The branch wxrks reads source files from (e.g. `main`).
Config path *	Path to the YAML config file (see below) in the repository.
Files	Optional — a comma-separated list of specific files to sync (e.g. `README.md, terms.json`). 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 — everything else must be filled in before wxrks will let you sync.

Bitbucket 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.

Step 3: Add the YAML config file to your repository

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 pull request. It must be committed to the repository 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:
- "locales/{lang}/{filename}" — writes each translation under a per-language subfolder, leaving the original untouched.
- "{filename}" — overwrites the original file in the repository root.
- "path/{filename}" — overwrites the original file in place, at that path.
- "{sourceFilePath}" — overwrites the original file wherever it actually is, preserving its full path.
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 repository 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 commits the translated files to a new branch — separate from your source branch, without overwriting the originals — and automatically opens a Pull Request against your main branch. Review and approve it using Bitbucket's normal pull request 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.

Using the wxrks Connectors Interface — the UI chrome shared by every connector (Configs list, Sync, filtering).
wxrks - GitLab Connector — the equivalent connector for GitLab-hosted repositories.

wxrks - Bitbucket Connector