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.
How the GitHub Connector Works
- 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
- 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
- On-Demand Mode: content is sent to Smartling for translation and delivered back to the default branch manually by a user in Smartling.
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:
- 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.
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. You can configure the configuration set on pull request mode to watch only published PRs or published and draft PRs.
Once translatable files are found, the GitHub Connector will create a "Smartling Translation" status check on that pull request, and automatically sends those files to Smartling for translation. The status check can be configured in GitHub so that the pull request remains locked until translations are done (Under "Branch protection rule" > "Require status checks to pass before merging").
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 resolves the status check on 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.
- 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.
- They 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 create a "Smartling Translation" status check on the pull request. If status checks are configured in GitHub as required to pass before merging, the pull request cannot be merged until the translation job is completed.
- The GitHub Connector adds the content of the commit on a PR to an existing Job, if possible, unless configured to create a new Job
- The Job name will contain the name of the designated branch and the commit number.
- 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 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.
- 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 main (master) branch is now “fully translated”.
- The "Smartling Translation" status check on the main (master) branch’s pull request is resolved.
- The main (master) branch’s pull request can now be accepted and merged with the main branch.
Single Branch Mode Translation Flow
- 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.
- Your developer changes the designated branch via pull requests or direct commits.
- 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.
- The GitHub Connector adds the content of the commit to a new Job, unless configured to reuse an existing one if possible.
- The Job name will contain the name of the designated branch and the commit number.
- 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.
- 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.
- 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 Smartling. At 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.