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 user can then merge the translated files to your main (master) branch, one commit per file, per language. 

Visual Context is not generated automatically, however, if you require visual context for your content's translation, look into integrating with the Smartling Context Chrome Extension or JS Library. Alternatively, you can always manually upload visual context via the Context tab in the Smartling dashboard.

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. The connector can be configured to monitor a specific branch in a specific repository for any changes to your resource files. The repository, branch and path to resource files are defined in the Configuration Set. You can create multiple Configuration Sets in one project.
For best practices, please consult your Customer Success Manager or Solution Architect.
The GitHub Connector has two different modes available:
  1. Pull Request Mode: monitors pull requests to the configured branch and jumps into action to upload resources files to Smartling if a pull request contains changes to those files
  2. Single Branch Mode: monitors commits to the configured branch and jumps into action to upload resources files to Smartling if a commit contains changes to those files
The resource files are uploaded to the Smartling project with a filename that includes the branch name they are being uploaded from in GitHub. These files are added to a translation Job in Smartling. You can configure the connector in the Configuration Set to automatically authorize the Jobs (see step 12) for translation.
When the translation Job is complete in Smartling, the connector creates a translation delivery branch, commits the translated files, and creates a pull request containing the translations to the branch where the source files were uploaded from.
Alternatively, you can choose to manually export translations from Smartling to GitHub within in any enabled configuration set.

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 does not support rebasing when set to Pull Request Mode. It may lead to unexpected results with the PR and unexpected Connector behavior. However, as Single Branch Mode works with commits only, there are no issues with rebasing of feature branches when the Connector is set to Single Branch Mode.

Ensure your content branch naming conventions do no begin with "Smartling". The Connector interprets all branches starting with smartling- as self-created branches with translations and does not monitor changes in them (does not handle content changes in them).

The GitHub Connector requires the user integrating the connector to be an Admin in the repository, and a member of the organization in GitHub 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 Org member/Repo 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 Org member/Repo 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 an open "Daily Uploads" Job, if there is one in progress. If there is not, the Connector will create a new Job.

To enable new Job creation for each commit, reach out to your Smartling Representative.

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 Org member/Repo 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 Org member/Repo 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 Org member/Repo 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 changes 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 add the content if the commit to an open "Daily Uploads" Job, if there is one available.
    • If there is not one already in progress, the Connector will create a Job in your Smartling project. The Job name will contain the name of the designated branch and the commit number.
    • To enable new Job creation for each commit, reach out to your Smartling Representative.
  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 Org member/Repo Admin user can review and merge the pull request with translations to the designated branch.

Manually Export Translations to GitHub

By default, the GitHub Connector returns translated files to the delivery branch in GitHub when the Job is complete in SmartlingAt any time, you can choose to send translations back to a designated branch in GitHub.

This feature is supported on both Pull Request Mode and Single Branch Mode.

To manually export translations:

  • On any enabled configuration set, click Export Translation and select a branch, files, target languages and translation state (current or published).
    • Current translations: The content in its current state in the workflow.
    • Published translations: All published translations in the specified language for the specified file.

The translation delivery process will not be instant and will take some time.

Was this article helpful?