-
Pull Request Mode - monitors pull requests and draft pull requests, and uploads resource files if changes have been made
- Single Branch Mode - monitors commits and uploads resource files if changes have been made
- On-Demand Mode - content is sent for translation and delivered back manually
Note: Content branch names must not begin with "Smartling" as the Connector interprets branches starting with "smartling-" as self-created ones with translations and will not monitor changes in them.
GitHub Connector Modes
Pull Request Mode
Pull Request Mode watches a selected branch in your repository for all pull requests and draft pull requests containing translatable files. You can customize the configuration set not to watch draft PRs.
Once translatable files are found, the GitHub Connector creates a "Smartling Translation" status check on that pull request, and automatically sends those files to Smartling for translation. Pull Requests with the "Smartling Translation" status should not be merged or deleted until the translations have been successfully delivered.
Status Checks
- If the connector created a translation job and waiting for its completion, the status is
Pending - Pull request is being translated - If the connector is delivering translation/changes to a new translation PR, the status is
Pending - Translated files are being delivered to the branch - If the connector has delivered changes and is waiting for translation PR merge, the status is
Pending - Translated files have been delivered. Waiting for translation pull request merge
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").
Alternatively, you can enable Translation Hold on the configuration set to pull request mode. This setting automatically applies a "hold" label to your GitHub pull requests. This instructs the connector to put a hold on the creation of Smartling translation jobs until the label is manually removed in GitHub. When a pull request is ready to be translated, removing the label manually in GitHub will trigger the creation of translation jobs.
Translation Delivery
Once the translation job is completed for all configured languages, the connector creates a separate Smartling Translation branch from the original branch that triggered the translation Job from the Pull Request.
This new branch contains the translated files, and follows the naming convention:
smartling-translation-[status]-[Job UID]-from-[original branch name that triggered
the PR]
e.g.: smartling-translation-completed-94wpkn6cgztj-from-create-original-string
Note: Ensure there are no custom security rules on your GitHub that prevent the creation of translation branches, as this will block translation delivery.
The connector then raises a Pull Request against the source branch, which then needs to be merged into the source branch. You can customize the configuration set to add all developers who worked on the pull request (committers) as reviewers in GitHub to the translation pull request.
Once this Pull Request is accepted and merged into the source branch, the "Smartling Translation" check is marked as resolved, unlocking the original Pull Request. Both the source files and their corresponding translations can then be merged into the watched branch.
Watch our video explanation of Pull Request Mode here.
Single Branch Mode
With the Single Branch Mode, the Connector monitors the watched branch for commits. As soon as a commit is made, Smartling creates a translation Job for the file. Upon completion of the translation Job for all languages, the translations are delivered to GitHub in a separate Smartling Translation Branch that is created from the initial commit.
To deliver the translated files, the Connector raises a Pull Request to the watched branch labeled "Smartling translations are completed" or "Smartling translations are updated". If no conflicts are present, the Pull Request can be merged and the Smartling Translation Branch can be deleted.
Tip: Watch our video explanation of Single Branch Mode here.
On-Demand Mode
On-Demand mode gives you full control over exactly when files are sent for translation and exactly when translations are delivered back to GitHub. Similar to the other modes, when set to On-Demand mode, the connector is integrated with a specific branch within your repository. However, unlike the other modes, it is not monitoring pull requests or commits on branches. It is simply connected to the branch, ready to send content to Smartling when you are.
Once translations are complete, you can manually export the translated content back to GitHub. The manual export delivers translations in a branch using this naming convention: smartling-translations-<yyyyMMddHHmmssSSS>
On-Demand mode is recommended if you want full control over when content is sent to Smartling for translation. It is also recommended if the original PR was accidentally merged before translation completion.
Note: Reach out to your Customer Success Manager about enabling the On-Demand mode option in your GitHub project.
Watch our video explanation of On-Demand Mode here.
Which Mode Is Best For You?
Depending on the needs of your organization, your development process (do you use pull requests or commits, and how often), whether you want translations delivered so they can be merged and tested at the same time as the original copy, or whether you need control, you can select one of three modes for each configuration set: Pull Request, Single Branch, or On Demand.
Different modes can even be used within the same Smartling project, as part of separate configuration sets. We recommend testing each configuration mode and discussing with your Smartling representative.
Pull Request mode requires all features to be fully translated before they are merged into the main branch, helping to ensure that no untranslated strings are released on the production version of your application. The original pull request will stay locked until all translations are merged, preventing the source branch from being deleted.
Tip: 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 automates the creation of translation jobs and delivery of translated content. This mode is ideal if you need to merge the source language and continue testing your application while translations are in progress. This mode also allows you to delete the source branch as soon as the translation job has been created.
Tip: 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.
On-Demand mode does not offer any automation when it comes to the creation of translation jobs or the delivery of translated files, but it allows you to control when new files are uploaded for translation and when translations are exported back to GitHub.
Tip: On-Demand Mode is recommended if your content and development process require greater control over for its localization.
Early Delivery of Translations on Pull Request and Single Branch Mode
If your development process requires any translation to move forward, you can get prepublished translations delivered early on Pull Request Mode and Single Branch Mode by enabling Early Delivery. Prepublished translations are delivered in an early delivery pull request, which removes the status checks and unblocks the original pull request, allowing you to merge both source and translations to the feature branch before the translation Job is complete. For more information, read our documentation on how to Get Translations Before Job Completion with Early Delivery.