Improve your i18n Workflow with the Phrase GitHub-Sync

Developers should focus on developing new features, not managing the translation process. Learn how an efficient translation management workflow that improves collaboration between localization managers, translators and developers can look like.

Improve your i18n Workflow with the Phrase GitHub-Sync. Getting localization right can be a tedious, time consuming task. There are many parties involved, each with different priorities. On one hand, developers want to introduce new features without having to think about the localization process. On the other hand, localization managers want to ship new translations as soon as they are available.

As a developer I would be totally happy if I only needed to introduce new translation segments in the source code and could be confident that the localization process is started automatically. And, as a localization manager I would like my translation changes to be automatically integrated in the software without any specific interaction with the development team. Thankfully there are already localization tools like Phrase available that simplify the localization process a lot.

Many development teams are using GitHub for hosting their source code. It offers great features to support collaboration on software. To integrate one step further, it would be great to combine the localization process with the GitHub source code management process to benefit from an enhanced automatic workflow without the need of direct communication between both parties for every change.

By using the GitHub-Sync feature of Phrase this can be achieved. In Phrase, our new GitHub-Sync feature can improve collaboration between localization managers, translators and developers. It enables your localization managers to request the development team to release new translations with a single button click. It reduces the overhead of adding new keys manually to Phrase for developers as well. I want to present to you the setup and an example workflow of Phrase GitHub-Sync in this article.

If you’re already using GitHub for your development process then setting up GitHub-Sync for Phrase will help you to improve your current localization workflow even more. This guide also assumes you already have basic i18n capabilities in your app. The initial setup is done within minutes and enables a continuous localization workflow with Phrase and GitHub.

Initial GitHub Sync Setup

Lets assume we want to localize a Rails app with its source code being hosted on GitHub:

First of all, you need to create a new project on Phrase. If you don’t have a Phrase account at this time or don’t know how to create a project you should check out our “How to get started with Phrase” guide.

After your project has been created, you need to tell Phrase where in your source code the locale files can be found and how to match these against the locales in your Phrase project. This needs to be specified in an file named .phraseapp.yml that should be located in your project’s root folder. Don’t worry, you don’t have to do this from scratch. Instead you can use the phraseapp init command of our Phrase Client.

The phraseapp init command will prompt you for a Phrase API access token. You can create an access token for your user account inside the Phrase settings at https://phrase.com/settings/oauth_access_tokens.

After following the steps of the the phraseapp init command you should find a basic .phraseapp.yml configuration in your project’s root directory. The GitHub-Sync and most Phrase clients use this file for their configuration. Before adding and pushing this file to your git repository you should remove the access_token for security reasons! You can use an environment variable for your access token, if you also want to use the Phrase CLI tool. For the GitHub-Sync the token is not required.

Now your .phraseapp.yml should look like similar to this:

phraseapp:
  project_id: your_project_id
  file_format: yml
  push:
    sources:
    - file: ./config/locales/.yml
      params:
        file_format: yml
  pull:
    targets:
    - file: ./config/locales/;.yml
      params:
        file_format: yml

If your developer should be only use a specific locale to create new translation, you should only specify this locale as a push source.

Now, let’s push the file to our GitHub repository:

<code>
(master) $ git add .phraseapp.yml
(master) $ git commit "adds basic phraseapp.yml"
(master) $ git push origin
</code>

Next, you need to configure your Phrase Project to enable GitHub-Sync. But in order to do this you will need a GitHub access token with full repo scope. GitHub access tokens are user-based so you need to create the token for a user who has access to the project! You can create the token on your profile settings on GitHub (https://github.com/settings/tokens). Make sure your generated token has repo scope.

Now you can use this token to enable GitHub-Sync for your Phrase project. To do this you have to select the GitHub-Sync tab within your project settings. Check “enable GitHub-Sync” and add the token you created on GitHub to allow Phrase to access your repositories. Next, you can select the corresponding project and the branch you want to be synced. Select the branch all pull requests get merged into as Phrase will provide new translation via a Pull Request! (Usually this branch will be your “master” branch.)

You can use the “Validate Configuration” button to check whether your .phraseapp.yml is valid and readable. Every time you need to change some setting, for example a locale file mapping or you enable emoji support, you only need to change your .phraseapp.yml , push it to the GitHub branch you selected for GitHub-Sync and Phrase will apply the changes for the next sync.

Now you are ready to start your localization process with the Phrase GitHub-Sync!

A Continuous Localization Workflow With Phrase

There is no general workflow you have to follow using the GitHub-Sync feature because it depends on your existing development workflow and your project in general. That’s why I will show you an example workflow. This workflow should work for you if you are using feature branches and GitHub pull requests into your master branch .

Because your developers only should create new translations in the default language of the project I recommend to only specify the default locale as push source. Assuming English is your default language you need to change your push source like this:

<code>
  push:
    sources:
    - file: ./config/locales/en.yml
      params:
        locale_id: en
        file_format: yml
</code>

For pulling translations from Phrase into your git repository you should specify all locales, including the default language because your content editors may make changes to this locale as well such as fixing typos.

After finishing a feature in a separate branch, you can create a pull request to your master branch. After this pull request gets merged to master, you can use the “Import from GitHub” inside the Phrase Translation Center to import all new keys and translations into your Phrase project. If you want to automate this process you can “Enable auto import from GitHub” in your project’s GitHub-Sync settings. Then, you also need to add the GitHub webhook notification as described here:

After Phrase has imported the new keys from GitHub, your translation team will see missing translations and can start to work on the translation. When they’re finished with the translation, they can use the “Export to GitHub as Pull Request” button on the Phrase locale overview to create a pull request with the updated locale data inside your GitHub repository.

The only thing left for the development team to do, is to merge the open pull request and deploy the new localized feature.

Your master should be deployable with all translations every time?

As you will already have noticed the time lag between merging the pull request with the new feature and the pull request of the translation team. Your master will contain missing translations during this time. You could use a fallback locale for this, e.g. falling back to your English localization. Or, this could not matter to you because you’re only building fixed releases from your master branch at certain points in time where you can ensure that all translations are present.

However, if your master branch needs to be deployable every time you should use some buffer branch like development to merge your feature branches into and then merge this branch into master after the translations are completed and merged.

A workflow for this scenario could look like this:

Some projects are using a development branch for merging feature branches besides the master or they’re using a master and a stable branch. This general flow will be easily adoptable to this setup, but remember to adapt the branch you want to synchronize with inside the Phrase GitHub Sync settings of your project.

Originally published on The Phrase Blog.