GitHub Connector

GitHub Connector Overview

If your localization resource files are in a GitHub repository, the Smartling GitHub Connector may be the ideal option for automating the process of sending source files to Smartling for translation.

The Smartling GitHub Connector monitors your repository for translatable files, automatically sends these files to Smartling for translation, and automatically delivers them back to your repository as soon as the Job in Smartling is complete. A GitHub Admin user can then merge the translated files to your main (master) branch, one commit per file, per language. 

Automatic Visual Context is not supported. If you require visual context for your content's translation, look into the Smartling Context Chrome Extension or JS Library.

The Smartling hosted GitHub Connector is designed to work well with standard development practices. It’s important to understand how and when files will move between the repository and your Smartling project.

This article covers:

  1. How the GitHub Connector Works
  2. Important Prerequisites
  3. Options for Setting up the GitHub Connector 
  4. Pull Request Mode Translation Flow
  5. Single Branch Mode Translation Flow

How the GitHub Connector Works

The GitHub Connector:

  • Acts like a phantom developer focused on getting your resource files translated.
  • Monitors pull requests in a GitHub repo, based on your configuration set in Smartling.
    • The configuration set directs the GitHub Connector to monitor pull requests for certain files, in a specific branch, in a specific repository.
    • It is not recommended having two configuration sets on the same repo.
    • Each configuration set is associated with a specific GitHub Admin user.
    • Choose to set the GitHub Connector to Pull Request Mode or Single Branch Mode in the configuration set.
    • You can configure as many configuration sets as you need.
  • When a pull request has been committed in GitHub on files that require translation, the Connector uploads the original language files that require translation to your Smartling project, packaged as a Job.
    • They're uploaded to the Smartling project using a URI that includes the branch name they are being uploaded from.
  • When the translation Job is complete in Smartling, based on your configuration set, there are two methods to how the GitHub Connector will commit the translated versions of the files:
    1. Pull Request Mode: Commits into a new branch in your repository.
    2. Single Branch Mode: Commits into the main (master) branch in your repository.
  • The GitHub Connector will make a pull request in GitHub so that you can review and properly merge these changes.

Important Prerequisites

The GitHub Connector is not compatible with GitHub Enterprise (self-hosted repositories). However, if your GitHub Enterprise is hosted on github.com, this is compatible with the GitHub Connector. 

The GitHub Connector requires a GitHub Admin user specifically for use with Smartling. This user will be used to authenticate Smartling’s access to your repo when configuring the Smartling project, and will provide access to the repository. It will also be the user who is associated with the branches, commits, and pull requests that are made in your repository.

If you feel that any of the above may not be compatible with your development process, see Options for Automation with Source Repositories for an overview of other options.

Additional Authorization 

Once you allow Smartling to access your GitHub account, via the OAuth flow, there may be an additional authorization required by your GitHub admin. For example, your GitHub account may have been set up by a third-party application where authorization must be performed by an "owner".

If this is the case:

  1. Go to your GitHub Settings > Applications > Authorized OAuth Apps.
  2. Select Smartling GitHub Connector and then select request access. Until an owner grants access, the status will show as "Access request pending". During this time, the connector will fail to connect.

Options for Setting up the GitHub Connector 

Pull Request Mode

Pull Request Mode watches a selected branch in your repository for all pull requests containing translatable files. Once translatable files are found, the GitHub Connector will “flag” (lock) that pull request, and automatically sends those files to Smartling for translation. The "flagged" (locked) pull request remains locked until translations are done.

Once the translation Job is complete, the GitHub Connector creates a new translation branch and pull request in your repository, containing all translations, one file per language. The GitHub Admin user can then merge this pull request into the destination branch, which then removes the flag from the initial pull request.

Pull Request Mode is recommended if you want to make sure all feature content is completely translated, and you can wait to merge feature pull requests until all translations are done.

Single Branch Mode

Single Branch Mode watches your selected branch for all commits containing translatable files. When the integration is first switched on, it will upload all translatable files from the designated branch and add them to a job. Moving forward, whenever a commit to those files has been detected, the GitHub Connector automatically uploads the updated files to Smartling for translation. None of your development pull requests are flagged (locked), so development work can continue even without translations.

Once the translation Job is complete, the GitHub Connector creates a pull request in your repository, containing all translations, one file per language. The GitHub Admin user can then merge this pull request into the selected branch when they are ready to do so.

Single Branch Mode is recommended if you want development work to continue unimpeded by translation work. With this mode, you can release your product or features in the original language first, and roll out other languages later when translations are ready.

Pull Request Mode Translation Flow

The GitHub Connector relies on your team, using pull requests, to start this process.

  1. The GitHub Admin user creates branches to work on changes to your source code.
    • In those branches, make edits to the original source language versions of your repositories’ localization resource files. This includes adding new files or modifying existing files.
  2. They make pull requests to merge the changes to your main (master) branch.
  3. If there are changes in the pull request to the resource files that require localization, the Smartling GitHub Connector will flag (lock) the pull request.
  4. The Smartling GitHub Connector will create a Job in your Smartling project.
    • This Job will be configured with the original language resource files, which will be uploaded using their branch’s name in the Smartling file URI.
  5. Translation happens according to your Smartling translation workflow which will include:
    • The Job is Authorized for translation by a Smartling user on your account. (By default, automatically authorizing a Job is disabled. To enable the feature, log in to Smartling and go to Project Settings > GitHub Settings then select Automatically Authorize All Jobs. This feature is only available for Enterprise customers.)
    • The translation work is performed using workflows that can contain multiple steps.
    • When all translations in the Job have been published, the Job is automatically updated to the completed state.
  6. The Smartling GitHub Connector will create a new “localization” branch from the branch where the pull request originated.
  7. Once the Job is complete in Smartling, the Smartling GitHub Connector will download the translated versions of the files from Smartling, and commit them to the “localization branch”, one commit per file, per language (locale).
    • The Smartling GitHub Connector will analyze every PR and try to deliver the translated version of the files. In the case that the PR makes a change to the files that don't require any translation work the connector can still deliver new versions of the files to reflect those changes even after the Job is automatically canceled (because there is no translation work to do.) Two examples of this will be if the only changes to the source file are that strings are deleted or non-translatable edits are made to the file (such as changing comments or structure).
  8. A pull request is made by the Smartling GitHub Connector for the localization branch that includes just the translated versions of the localization resource files.
    • The location and file names of these translated files will depend on your configuration.
  9. Review, accept, and merge the localization branch pull request.
    • The main (master) branch is now “fully translated”.
  10. The main (master) branch’s pull request is unflagged.
  11. The main (master) branch’s pull request can now be accepted and merged with the main branch.

Single Branch Mode Translation Flow

  1. The GitHub Admin user create branches to work on changes to your source code.
    • In those branches, make edits to the original source language versions of your repositories’ localization resource files. This includes adding new files or modifying existing files.
  2. Your developer makes changes to the designated branch via pull requests or direct commits. 
  3. When there is a commit to the designated branch with changes to translatable files, the GitHub Connector will automatically upload the updated files to Smartling for translation.
  4. The GitHub Connector will create a Job in your Smartling project. The Job name will contain the name of the designated branch and the commit number.
  5. Translation happens according to your Smartling translation workflow which will include:
    • The Job is Authorized for translation by a Smartling user on your account. (By default, automatically authorizing a Job is disabled. To enable the feature, log in to Smartling and go to Project Settings > GitHub Settings then select Automatically Authorize All Jobs. This feature is only available for Enterprise customers.)
    • The translation work is performed using workflows that can contain multiple steps.
    • When all translations in the Job have been published, the Job is automatically updated to the completed state.
  6. Once the Job is completed, the Smartling GitHub Connector will create a new translation delivery branch, commit the translated files (one commit per file, per locale), and create a pull request from the translation delivery branch to the designated branch, containing all translations.
    • The location and file names of these translated files will depend on your configuration.
  7. The GitHub Admin user can review and merge the pull request with translations to the designated branch.

Was this article helpful?