Connect GitLab, Bitbucket or Azure Repos
Connect a GitLab, Bitbucket or Azure Repos repository so a push to the default branch comes back as a merge or pull request with translations.
transglot connects to GitLab, Bitbucket and Azure Repos with an access token you create on the repository side, plus a webhook that tells transglot when you push. On a push to the default branch, transglot extracts the changed source strings into your project, translates them, and opens one merge request (GitLab) or pull request (Bitbucket, Azure Repos) from its own transglot/sync branch. It never commits to your branches.
| Host | Supported | Not supported |
|---|---|---|
| GitLab | GitLab.com | Self-managed GitLab |
| Bitbucket | Bitbucket Cloud | Bitbucket Server and Data Center |
| Azure Repos | Azure DevOps Services (dev.azure.com) | Azure DevOps Server |
For GitHub, use the GitHub App instead.
Requirements
- Plan: Team or above. On a lower plan the host's card on the Integrations page offers Upgrade plan instead of Connect.
- Role: Admin of the transglot workspace, or an Owner of its account.
- On the host: permission to create an access token and a webhook (or Service Hook) on the repository.
- Your files: one source locale file per repository, at a path that contains the locale code, for example
locales/en.json.
Connect a repository
Open Integrations in your workspace and select Connect on the GitLab, Bitbucket or Azure Repos card. The page shows the URL your webhook must call: copy it from there.
Create a project access token
In your GitLab project, create a project access token with the api scope. It starts with glpat-.
Add the webhook
In the GitLab project, go to Settings, Webhooks. Add the Webhook URL shown on the transglot GitLab page, choose a Secret token (any long random value) and enable the Push events trigger.
Fill in the connection
Under Connect a project, enter:
| Field | What to enter |
|---|---|
| Project | The transglot project this repository feeds |
| GitLab project ID (numeric) | The numeric ID shown on the project's overview page in GitLab |
| Project path (group/project) | For example acme/website |
| Default branch | For example main |
| Project access token | The token from step 1 |
| Webhook secret token | The same value as the webhook's Secret token |
| Source path, Format, Source locale, Target locales (comma-separated, blank = all) | See Describe your files |
Select Connect project.
When it saves, transglot confirms with the repository name, and the connection appears under Connected projects (GitLab) or Connected repositories. Tokens and secrets are stored encrypted and never shown again.
Describe your files
| Field | What to enter |
|---|---|
| Source path | Where your locale files live, with {locale} in place of the locale code, for example locales/{locale}.json |
| Format | The file format, for example json_nested. See file formats |
| Source locale | The locale your team writes in, for example en |
| Target locales (comma-separated, blank = all) | The locales to deliver, for example fr, de, es. Leave it blank for every target language in the project |
What happens on a push
- You push to the default branch, changing the source locale file.
- transglot extracts the new and changed strings into the project, where translation memory, the glossary and quality checks apply to them.
- If automatic translation is on for the project, the new strings are translated. A translation your team has edited or reviewed is never overwritten by AI.
- transglot writes one file per target locale, at the same path pattern, to the
transglot/syncbranch and opens a merge or pull request. If one is already open, it is updated instead of a second one being opened.
Each connection has its own webhook secret, and transglot checks it on every delivery: a delivery without the right secret is rejected, so one connection cannot be used to trigger another.
Check what happened
The host's card on the Integrations page shows the last sync attempt, its status (Completed, Nothing to sync, Not configured, Failed or Blocked) and a sentence saying what happened. "We did not run this sync." means transglot did not start, and the sentence after it says why. "This sync ran and did not finish." means it started and hit a problem. A card whose last run failed carries a failing flag.
Change or disconnect
To change a connection's files or locales, fill in the form again for the same repository and save. Leave the token and secret fields blank to keep the stored values.
To stop syncing a repository, select Disconnect on its row and confirm. No new merge or pull requests are opened; anything already open stays open. Delete the webhook or Service Hook on the host as well.
Troubleshooting
Write the path with {locale} where the locale code goes, for example locales/{locale}.json.
A repository can feed only one transglot workspace. GitLab says "This GitLab project is already linked to another transglot workspace.", Bitbucket and Azure Repos say the same of the repository. Disconnect it in the other workspace first.
Check that the push went to the default branch named on the connection and changed the source locale file. Then check the webhook on the host: its URL must be the one on the transglot page, its secret must match the connection's, and the push trigger must be enabled. GitLab, Bitbucket and Azure DevOps each keep a delivery history for webhooks that shows failed calls.
transglot could not read the source file at the pushed commit. Check the Source path and Source locale, and that the token can still read the repository.
The Default branch on the connection does not exist, or the token can no longer read the repository. Correct the branch name, or create a new token and save it on the connection.
The token can read but not write. Create a token with permission to push branches and open merge or pull requests, and save it on the connection.
For a step-by-step diagnosis, see Why is my repository sync not running?.