Skip to main content

Bitbucket

Pull files from Bitbucket and create pull requests from Lokalise.

Written by Ilya Krukowski

Use this app to exchange files with your Bitbucket repository. 

Once the app is set up, you can pull the files by using the Lokalise web dashboard. There will also be an incoming webhook set up, which you may use to automatically pull the files as they are pushed to Bitbucket by your developer team. 

Once the translations are done, you can trigger the creation of a pull request when exporting.

Setup

1. Connect your repository

Open your Lokalise project and proceed to Apps.

Find Bitbucket in the apps list, click on it and then press Install. Next, click Install again to authenticate via OAuth2.

After successfully authenticating, you can enter your Repository full name and Branch to pull from.

You must specify the platform of the files stored in this repo. As you export files from Lokalise you can trigger the Bitbucket app to create pull requests to repositories with a platform related to the exported file format.

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.

2. Select files to pull

Browse the selected repository and select the files you want to pull and import.

In most cases, in this step you will only need to select the base language files (the files that are being modified locally and then pushed to Bitbucket). After selecting a file, make sure its language is detected properly.

Then click Confirm to finalize the installation.

3. Add more repositories

As we recommend keeping all platform files within the same project, you may want to set up other repositories that apply to the same project. Click Add another repo to add more repositories.

4. Reconnect a connection

Each Bitbucket connection has its own authorization. If the authorization expires or stops working, you can reconnect without removing the connection and setting it up again.

You may need to reconnect if:

  • Pulls or pull requests stop working.

  • The connection's Logs show an authorization error.

  • The project was copied or restored from a snapshot.

To reconnect:

  1. Find the affected connection and click Reconnect.

  2. Confirm the action in the Reconnect configuration dialog.

  3. You'll be redirected to Bitbucket. Click Authorize to grant Lokalise access again.

  4. Once you're back in Lokalise, click Save.

Your repository, branch, selected files, and Pull options are preserved. There's no need to remove and recreate the connection.

Important: Bitbucket ends authorizations that haven't been used for three months. If a connection hasn't pulled files or created a pull request during that time, you'll need to reconnect it before using it again.

Copied projects

When you copy a Lokalise project or restore one from a snapshot, its Bitbucket connections are copied without their authorizations.

Click Reconnect on each copied connection before attempting to pull files or create pull requests.


Pulling files

Manual pull

Use the Pull now button on the app page. Clicking the button will add the pull to the system queue to be executed in the background.

If you need to adjust the options, click Pull options on the app page.

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

First pull after saving a connection

Normally, Lokalise skips files that haven't changed in Bitbucket since the previous pull. You can identify these files in Logs by the following message: skipped (file with same SHA was already pulled).

However, after you save a connection, the next pull imports all selected files again, even if they haven't changed in Bitbucket. This also happens after reconnecting or updating Pull options. During import, keys whose values haven't changed are still skipped.

Important: If Replace modified values is enabled in Pull options, this pull can overwrite translations edited in Lokalise with the values from your Bitbucket repository.

If you want to preserve your changes in Lokalise, disable Replace modified values before running the next pull.

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 and copy/paste the Auto-pull URL provided in the Lokalise app configuration into the URL text field, and tick the Repository > Push trigger:

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

If you're using project branching, keep in mind that app triggers can only be executed from the Lokalise master branch.

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

To actually create a pull request on Bitbucket, you should press Build only (this way you won't download a translation bundle to your local PC). To check the status of the pull request creation, return to the Bitbucket app page and click the Logs button.

Here is what happens as you trigger a new PR:

  1. A new branch is created from the last revision of the branch  you chose in the app setup. The branch name will look like this: lokalise-2018-03-12_15-14-13.

  2. A commit with all the files is created in the new branch.

  3. A pull request from the new branch to the previously chosen branch is created.

You may then review and merge a pull request in Bitbucket.

To initiate a pull request from the API, use the triggers=['bitbucket'] parameter with the /export endpoint. If you are using the CLI tool, use --triggers=bitbucket  as a parameter when performing the export.

Did this answer your question?