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

Bitbucket Sync

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


Bitbucket Sync relies on the .phraseapp.yml configuration file being present in your Bitbucket repository in order to know which locale files you want to sync with Phrase. This is the same file that the command-line Phrase Client uses, and it 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. If you wish, you can leave out your personal access token. These screenshots show what your .phraseapp.yml file might look like:

Bitbucket_1_Configuration File

Be sure that your .phraseapp.yml file contains the correct project ID. You can find the project ID in the project settings.

Connect your repositories to Phrase

Once your completed configuration file is in place, you can activate Bitbucket Sync and connect your repositories to Phrase.

1. Go to the Integrations tab.


2. Click Activate next to Bitbucket Sync. Then, choose the Bitbucket account you want to connect to from the menu that appears. When you click “Grant access”, your Phrase account will be connected to your Bitbucket account.


3. Click Connect Repository. Then, choose the repository you want to connect from the menu.


4. Connected repositories are listed on the Bitbucket Sync page. A green dot appears next to an active repository. A red dot appears next to a repository with a missing or invalid .phraseapp.yml configuration file.

Bitbucket_5_Connected_Repositories_OverviewImport from Phrase to Bitbucket

After activating Bitbucket Sync and connecting a repository to Phrase, you can import your locale files:

1. In your Bitbucket account, go to the repository you want to sync.

2. Select a branch of the repository. In its action menu, click “Import from Phrase” to pull translations from Phrase into the repository.


3. Bitbucket will redirect you to the new pull request in your Bitbucket account.


4. When you’re ready, you can approve, merge or close the pull request in Bitbucket.

Why a pull request?

Phrase delivers locale file updates as pull requests so that you can review all the changes. This keeps you in control of what actually goes into the branch you chose (usually “master”).

Export from Bitbucket to Phrase

You can export your locale files from Bitbucket to Phrase by following these steps:

1. In your Bitbucket account, go to the repository you want to sync.

2. Select a branch of the repository and click “Export to Phrase” to push translations from the repository into your Phrase project. This uploads new files to Phrase, updating your keys and translations.

3. After exporting the files, Bitbucket will redirect you to a page with a link to your Phrase project. Click the link to go to your project’s dashboard in Phrase. The latest uploads appear on the right. Note that it can take some time for the new uploads from Bitbucket to appear.

4. To see a detailed upload summary, click an upload in the list or go to “Uploads” in your project. A green dot appears next to a successful upload, while a red dot appears next to a failed upload.


A red dot appears next to a repository with a configuration file that seems correct
Make sure that your configuration file includes at least one pull target (for importing into Bitbucket) and one push target (for exporting into Phrase). Double-check that the project ID is valid and belongs to the Phrase project you want to sync your files with.

Nothing gets imported or exported

Make sure that your .phraseapp.yml configuration file contains valid pull and push targets. Note that many file formats require locale_id to be defined for each source, since the files don’t contain any locale information. You can always use the Phrase Client to check if your configuration file behaves as you expect. If an upload fails, a red dot will appear next to it on your Phrase dashboard and in the Uploads section, as described above.

Changes to a locale in Bitbucket don’t appear in Phrase after a successful export

Make sure to include the update_translations parameter in your .phraseapp.yml configuration file. If this parameter is set to true, changes to existing translations will be transferred into Phrase, overwriting any content that’s already present. For more information, refer to the client configuration documentation.

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

Make sure you have the latest version of the Phrase Bitbucket add-on installed. If you can’t find some features described here, go to Manage Integrations in your Bitbucket account and click Update in the entry for the Phrase add-on.


A repository is missing from the Connect Repository menu in Phrase

You can only connect Bitbucket repositories that you are the owner of. If a repository doesn’t appear in the menu, you are likely not its owner. You can check ownership in the repository overview in your Bitbucket account.


Can I use Bitbucket Sync via API?

Yes. Refer to the API Bitbucket Sync documentation to learn how.

Are there any limitations when using Bitbucket Sync?

Yes. Currently, these limitations exist:

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

How can I deactivate Bitbucket Sync?

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

Can I remove the integration after activating it?

Yes. After disconnecting your repositories in Phrase, go to Manage Integrations in your Bitbucket account. Click the Phrase Integration add-on, and then click Remove. You can reactivate the integration again at any time from the Integrations tab in Phrase.

Why does Phrase need read and write access?

Phrase needs read access to import files from your Bitbucket repositories. It also needs write access to export files to your Bitbucket account.

Do I need to put my access token in the configuration file? 

No. Your .phraseapp.yml file only needs to contain the correct project ID, a valid push target and a valid pull source. An access token is automatically created when you activate Bitbucket Sync.

Bitbucket Sync still doesn’t work.

Contact us — we’re happy to help.

Further reading