1. Help Center
  2. Phrase for Developers
  3. Using version control systems with Phrase

Bitbucket Sync

Phrase Bitbucket Sync lets you sync your Phrase projects with your Bitbucket repositories easily.


In order to identify which locale files you want to sync with Phrase, we rely on the .phraseapp.yml configuration file being present in your Bitbucket repository.

This is the same file as used by our CLI client and defines which files you want to import from Phrase to Bitbucket (pull) or export from Bitbucket to Phrase (push).

Set up your Phrase configuration file as described here, with the exception that you don’t have to write your personal access token into it. In the following you find an example how your .phraseapp.yml might look like:

Make sure that the right Project ID is specified in the .phraseapp.yml configuration file present in your repository! You find the Project ID in the project settings of a project.

Connect your repositories to Phrase

If you have set up and uploaded your configuration file to Bitbucket, it’s time to activate Bitbucket Sync and connect your repositories to Phrase:

1. Go to the “Integrations” tab.

2. Click the “Activate”-button next to Bitbucket Sync and select the Bitbucket account you want to grant write and read access to the repositories from the appearing dropdown. After clicking “Grant access”, your Phrase account is connected to your Bitbucket account.

3. Click “Connect Repository” and select a repository you want to connect from the dropdown.

4. Once a repository is connected, it is listed on the Bitbucket Sync page. Green means that it’s active, red means that your .phraseapp.yml  configuration file is invalid or non-existent.


Import from Phrase to Bitbucket

If you have activated the Bitbucket Sync and connected your repository with Phrase, you now can import your locale files easily:

1. Go to your Bitbucket account and from there to the repository you want to sync.

2. Select the repository’s branch and click “Import from Phrase” to pull your translations from Phrase into your Bitbucket repository.

3. You now get redirected to the pull request which was automatically created in your Bitbucket account.

4. You can finally approve, merge, or close the pull request in Bitbucket.


Why a pull request?

We’re delivering locale file updates as pull requests so that you can review all changes and thus remain in charge of what actually goes into your selected branch (usually ‘main’).

Export from Bitbucket to Phrase

You can export your locale files from Bitbucket to Phrase easily by following the below steps:

1. Go to your Bitbucket account and from there to the repository you want to sync.

2. Select the repository’s branch and click “Export to Phrase” to push your translations from your Bitbucket repository into your Phrase project. This simply triggers new file uploads to Phrase by which your keys and translations will be updated.

3. On the following page you then see a link to your Phrase project, which you can click to get redirected to the dashboard of this project. Here you can see a list of the latest uploads on the right. Please be aware that it can take some time until the new uploads from Bitbucket appear, because the upload works asynchronously.

4. You can now click on an upload to see the details in it’s upload summary, or you can go to “Uploads” in your project. Here you can also see if an upload was successful (green) or not (red).


The validation fails although the configuration file seems correct

Make sure you have set up at least one pull target (for the import into Bitbucket) and one push target (for the export into Phrase) entry in your configuration file. Double-check if you have entered a valid Project ID and that the Project ID belongs to the Phrase project you want to sync your files with.

Nothing gets imported or exported

Please make sure that your .phraseapp.yml configuration file contains valid pull and push sources. Note that a lot of file formats require the locale_id to be defined for each source since they don’t contain any information on the locale in the file itself. You can always use the Phrase Client in order to check if your configuration file behaves as you expect. If an upload should fail, you can see this in your Phrase projects dashboard or in the “Uploads” section as described above.

I made changes to a locale in Bitbucket that are not visible in Phrase after a successful export

Please make sure to include the update_translations parameter in your .phraseapp.yml configuration file. If set to true, your changes to existing translations will be transferred into Phrase, overwriting content already present. For more detailed information, please refer to the client configuration documentation.

I can’t find all Phrase features in my Bitbucket account

Make sure that you have the latest version of our Phrase Bitbucket add-on. If you miss some features described here, go to “Manage Integrations” in your Bitbucket account and “Update” the Phrase add-on.

My Bitbucket Repository is not visible in the “Connect Repository” dropdown menu in Phrase

Please note that you can only connect Bitbucket repositories that you are the owner of. If the repository is not visible in the drop-down, that probably means you are not the owner of it. Please refer to the person owning the repository. You can check ownership in your repository overview over at Bitbucket.


Can I use the Bitbucket Sync via API?

Yes, please refer to the API Bitbucket Sync documentation.

Are there any limitations when using the Bitbucket Sync?

Yes. Currently, you encounter the following limitation:

  • Bitbucket Sync cannot be used with Bitbucket Server, only Bitbucket Cloud
  • Bitbucket sync currently does not support the parameter fallback_locale_id

How can I deactivate the Bitbucket Sync?

You can deactivate your Bitbucket Sync by deleting the Phrase add-on in your Bitbucket account. If you only want to disconnect a single repository, simply go to the “Integrations” tab in Phrase, click “Configure” and delete the respective repository connection.

Can I remove the integration after I activated it?

Yes, it is possible to entirely remove the connection to Bitbucket. After disconnecting your repositories in Phrase, visit the Manage Integration settings in your respective Bitbucket account, click on the Phrase Integration add-on and subsequently on Remove. When you go back to your Phrase account and reload the page you will land on the Phrase integrations tab. This is also where you can activate the connection again anytime you like.

Why does Phrase need read and write access?

Read access is required for the import of files from your Bitbucket repositories to Phrase (will be possible in the future) and write access is required to export files from Phrase into your Bitbucket account.

Do I need to put my access token into the .phraseapp.yml? 

No, you don’t. You only have to specify the right Project ID and valid pull sources. An access token is automatically created when you activate Bitbucket Sync.

It still doesn’t work?

Contact us — we’re happy to help.

Further reading