In order to identify which locale files you want to sync with PhraseApp, 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 PhraseApp to Bitbucket (pull) or export from Bitbucket to PhraseApp (push).

Set up your PhraseApp 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 PhraseApp

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

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 PhraseApp 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 PhraseApp to Bitbucket

If you have activated the Bitbucket Sync and connected your repository with PhraseApp, 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 PhraseApp” to pull your translations from PhraseApp 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 ‘master’).

Export from Bitbucket to PhraseApp

You can export your locale files from Bitbucket to PhraseApp 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 PhraseApp” to push your translations from your Bitbucket repository into your PhraseApp project. This simply triggers new file uploads to PhraseApp by which your keys and translations will be updated.

3. On the following page you then see a link to your PhraseApp 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 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 PhraseApp) entry in your configuration file. Double check if you have entered a valid Project ID and that the Project ID belongs to the PhraseApp 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 PhraseApp Client in order to check if your configuration file behaves as you expect. If an upload should fail, you can see this in your PhraseApp projects dashboard or in the “Uploads” section as described above.

I made changes to a locale in Bitbucket that are not visible in PhraseApp 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 PhraseApp, overwriting content already present. For more detailed information, please refer to the client configuration documentation.

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

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

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

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

How can I deactivate the Bitbucket Sync?

You can deactivate your Bitbucket Sync by deleting the PhraseApp add-on in your Bitbucket account. If you only want to disconnect a single repository, simply go to the “Integrations” tab in PhraseApp, 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 PhraseApp, visit the Manage Integration settings in your respective Bitbucket account, click on the PhraseApp Integration add-on and subsequently on Remove. When you go back to your PhraseApp account and reload the page you will land on the PhraseApp integrations tab. This is also where you can activate the connection again anytime you like.

Why does PhraseApp need read and write access?

Read access is required for the import of files from your Bitbucket repositories to PhraseApp (will be possible in the future) and write access is required to export files from PhraseApp 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

Did this answer your question?