Use this app to integrate your Lokalise project with Bitbucket Enterprise.

Initial setup

Generating personal access token

First of all, you will need to generate a personal access token. To achieve that, open Bitbucket Enterprise, click on your avatar and choose Manage account. Then switch to the Personal access tokens tab and click Create a token.

Give your token a name and make sure to choose Write permission for Repositories.

Click Create and copy the generated token (remember that you won't be able to see it again).

Connecting Lokalise to Bitbucket Enterprise

Open your Lokalise project and click Apps. Find Bitbucket Enterprise, press Install and then Connect. Provide your personal access token generated in the previous step, and a Host URL where your Bitbucket Enterprise resides:

Next, adjust other settings:

Choose your Repository to connect to
Choose a branch to use
Choose one or more platforms to include in exports
It is important to decide whether you would like the filenames to include a full path. It is not needed in most cases as you can configure the directory structure prefix in the pull request creation (export) step. However, when you have similar files in different subfolders, e.g. admin/locale.json and frontend/locale.json, you need to enable the Include path option in the filenames option. Keep in mind that if you already have files uploaded to the project, including a path in the filenames at this step would mean that you are uploading different files.

Once you are ready, click Select files to pull.

Make sure that you choose only the translation files from your repo. Once the files are selected, click Confirm.

At this point, your Bitbucket Enterprise app is ready for action!

Pulling translation data

To start translating your messages, pull the data from Bitbucket to Lokalise. You may simply click Pull now or Pull options to adjust the settings:

These options are similar to the ones presented on the Upload page.

Pull operation will be added to the system queue and performed in the background.

Auto-pull

When you are satisfied with the initial pull results, it is a good idea to set up a webhook in Bitbucket which automates pulling the changes to Lokalise as you push to Bitbucket.

In Bitbucket, navigate to Repository settings > Webhooks. Click Add webhook, give it a name and copy/paste the Auto-pull URL provided in the Lokalise app configuration into the URL text field. Choose one or more events and then click Create.

Please note that currently we are in the process of migrating all auto-pull URLs from app.lokalise.com to api.lokalise.com subdomain. Thus, on the app's page you may still see app.lokalise.com specified for the auto-pull URL but it is very much recommended to change it to api.lokalise.com when pasting to Bitbucket.

Pull requests

As the translations are being completed, via download page Lokalise can create the pull requests with the exported files, which you can then merge to a selected branch.

In order to create a pull request, you need to perform a project export with the Bitbucket Enterprise trigger enabled. It is a good idea to use the Preview button first, so you can see the resulting file/folder structure before triggering the creation of a pull request.

We would recommend only triggering pull requests only to the repos of the platform that match the file type you are exporting, i.e. if you are exporting in a JSON format, Lokalise will only create pull requests in repositories with the Web platform.

Known limitations

By default, the maximum file size is 5MB. This can be controlled with the content.upload.max.size option.
There's no "single commit" option.
Requests from Lokalise to the self-hosted Bitbucket server have 10 seconds timeout