A Guide to Improving Localization Workflows with the GitHub Integration for Phrase Strings

Getting localization right can be a challenging, time-consuming task. There are many stakeholders 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.

Developers would be happy if they only needed to introduce new translation segments in the source code of a software product and also confident that the localization process was started automatically. Localization managers would like translation changes to be automatically integrated into the software without any specific interaction with the development team.

Thankfully, software localization tools, like Phrase Strings, can make the localization process much simpler.

The background

Many development teams use 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 for direct communication between both parties for every single change.

That's exactly what you can achieve with the GitHub integration for Phrase Strings, our string management platform.

In Phrase Strings, our GitHub integration 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. Let's have a look at how you can set it up and learn from a workflow example in this step-by-step guide.

If you're already using GitHub for your development process, then using the GitHub integration for Phrase Strings can help you improve your current localization workflow even more. We assume that you already have basic i18n capabilities in your app. The initial setup is done within minutes and enables a continuous localization workflow with Phrase String and GitHub.

Initial GitHub Sync setup

Let's say 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 in Phrase. If you don't have access to Phrase yet or don't know how to set up a project, you can have a look at how to create a project in Phrase Strings.

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 a file named .phrase.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 phrase init command of our Phrase Client.

The phrase init command will prompt you for a Phrase API access token. You can create an access token for your user inside the Phrase settings.

After following the steps of the  phrase init command, you should find a basic .phrase.yml configuration file in your project's root directory—the GitHub integration 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 integration, the token is not required.

Now your .phrase.yml should look similar to this:

phrase:

  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 only use a specific locale to create new translations, you should only specify this locale as a push source.

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

(master) $ git add .phrase.yml

(master) $ git commit "adds basic phrase.yml"

(master) $ git push origin

Next, you need to configure your Phrase Project to enable GitHub Sync. However, 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. 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 need 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. Selecting the branch will merge all pull requests, and Phrase Strings will provide new translations via a pull request (this would usually be your "master" branch).

You can use the "Validate Configuration" button to check whether your .phrase.yml is valid and readable. Every time you need to change a setting, for example, a locale file mapping or you enable emoji support, you only need to change your .phrase.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, we recommend specifying only the default locale as the push source. Assuming English is your default language you need to change your push source like this:

  push:

    sources:

    - file: ./config/locales/en.yml

      params:

        locale_id: en

        file_format: yml

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.

Should your master 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 and then merge this branch into the 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 beside the master or they're using a master and a stable branch. This general flow will be easily adaptable to this setup, but remember to adapt the branch you want to synchronize with inside the GitHub Sync settings of your project.