GitHub Sync


PhraseApp GitHub Sync lets you sync your PhraseApp projects with your GitHub repositories easily.

Prerequisites

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

The file is used by most PhraseApp clients and defines which files you want to import (push) and export (pull).

See the documentation to learn more about how to set up your PhraseApp configuration file.

Connect your project

If you have set up and uploaded your configuration file to GitHub, it’s time to connect your repository to PhraseApp:

  1. Go to the Project Settings of the project you want to connect and select GitHub Sync.
  2. Enable GitHub Sync and enter a valid GitHub personal access token. You can create an access token in your GitHub Settings. Make sure the access token has the repo scope (or public_repo if you want to sync with a public GitHub repository).
  3. Select the GitHub repository you want to sync with PhraseApp.
  4. Select the repository’s branch used to import (push) and export (pull) your locales (usually ‘master’)
  5. Click Validate Configuration to check if your access token and the configuration file is set up correctly.
  6. Click Save.

Your project is now connected to your GitHub repository!

Import

Importing your locale files to PhraseApp from your connected GitHub repository is easy:

  1. Go to the Locales section.
  2. If you haven’t created any locales yet, add at least your default locale.
  3. Click GitHub Sync > Import from GitHub
  4. Your locale files (defined as push source entries in your configuration file) are now imported into your PhraseApp project. This can take a few seconds and you will see the status as new updates in your project’s activity stream.

Auto-Import

You can also import your locales to PhraseApp after every commit to GitHub with Auto-Import:

  1. Go to your project’s settings in PhraseApp and select GitHub Sync.
  2. Enable the auto import option.
  3. Generate a payload url and copy it. Please note that this will automatically generate a PhraseApp access_token that can be managed in your Profile Settings
  4. Click Save.

Next, add a webhook to your GitHub repository in order to notify PhraseApp of new pushes:

  1. Go to your GitHub repository’s Settings section and select Webhooks & services
  2. Add a new webhook:
    • Payload-URL: Paste your generated payload url. https://phraseapp.com/api/v2/hooks/github?project_id=YOUR_PROJECT_ID&access_token=YOUR_ACCESS_TOKEN
    • Content-Type: application/json
    • Secret: leave blank
    • Let the webhook trigger just the push event
  3. Click Add webhook

You have successfully activated Auto-Import for your PhraseApp project and we will import locale files from your repository after every update pushed to the selected branch (usually ‘master’) of your repository.

Export

Exporting the most recent locale files to your repository is just one click away:

  1. Go to the Locales section.
  2. Click GitHub Sync > Export to GitHub as pull request
  3. After a few seconds, your most recent locale files are exported to your GitHub repository as a new pull request. You will see this as an update in your project’s activity stream, too.

You can now head over to your Github repository in order to merge (or close) the pull request.

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

Troubleshooting

The validation fails although the configuration file seems correct

Make sure you have set up at least one push source and one pull target 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

Please make sure that your .phraseapp.yml configuration file contains valid 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.

Auto-Import does not work

Go to your GitHub repository’s Settings section of the project you have enabled auto-import for and select Webhooks & services. Click on the webhook you’ve added in order to notify PhraseApp about changes. Make sure you have entered the correct Payload URL and it contains the valid Project ID and access token.

You can also examine the most recent deliveries for each webhook and check out the response for error messages returned by PhraseApp.

It still doesn’t work

Contact us — we’re happy to help.

Further reading