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, and getting translations into your repository, where you need them. 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.
The Smartling GitHub Connector is not compatible with Github Enterprise (self-hosted repositories).
The Smartling 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.
How the Smartling GitHub Connector Works
We rely on your team, using pull requests, to start this process. The Smartling GitHub Connector:
- Acts like a phantom developer focused on getting your resource files translated.
- Monitors pull requests in GitHub, based on your configuration set in Smartling.
- A configuration set is a configuration that directs the GitHub Connector to monitor pull requests for certain files, in a specific branch, in a specific repository. Each configuration set is associated with a specific GitHub Admin user. 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.
- The Connector will commit the translated versions of the files into a new branch in your repository when this translation job is complete in Smartling.
- The Connector will make a pull request in GitHub so that you can review and properly merge these changes.
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:
- Go to your GitHub Settings > Applications > Authorized OAuth Apps.
- 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.
Resource File Translation Flow
- 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.
- Make pull requests to merge the changes to your main (master) branch.
- If there are changes in the pull request to the resource files that require localization, the Smartling GitHub Connector will flag it.
- 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.
- Translation happens according to your Smartling translation workflow which will include:
- The Job is Authorized for translation. (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.
- The Smartling GitHub Connector will create a new “localization” branch from the branch where the pull request originated.
- 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).
- 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.
- Review, accept, and merge the localization branch pull request.
- The original branch is now “fully translated”.
- The original branch’s pull request is unflagged.
- The original branch’s pull request can now be accepted and merged with the main branch.