Smartling's GitHub Connector monitors your repository for files that need to be translated and automatically sends them to Smartling for translation. When the job is complete, the translated files can be delivered back to your repository automatically or manually. You can then merge the translated files to your main branch.
The GitHub Connector is hosted in Smartling, meaning all configurations are done in Smartling. The connector is designed to work well with standard development practices. It’s important to understand what qualifies as new content for translation, how and when files will move between the repository and your Smartling project.
How the GitHub Connector Works
The GitHub Connector tracks changes made to files within specific branches of your Organization's repositories and automatically sends them to Smartling for translation. You can customize which repository, branch, and files to monitor using Configuration Sets. A Configuration Set is Additionally, you can create multiple configuration sets for a single Smartling project, or integrate multiple repositories with multiple projects.
Sample Architecture
File Upload
- Pull Request Mode: monitors pull requests and draft pull requests, and uploads files if changes have been made.
- Single Branch Mode: monitors commits and uploads files if changes have been made.
- On-Demand Mode: files are manually sent for translation and manually delivered back to GitHub. As this is a manual mode, the translation flow outlined in this document refers to Pull Request (PR) and Single Branch (commit) modes.
Translatable files are uploaded from the configured branch to the Smartling project, and automatically put into a translation Job. Depending on the configuration set auto-authorize settings, Jobs can be authorized for translation automatically or manually.
When a file is uploaded to Smartling as a result of a pull request or commit in a GitHub branch, the file is translated and delivered as per the configuration associated with that version of the file.
It is important to remember that if you make any changes to the configuration, those changes will only affect files that will be uploaded to Smartling as a result of pull requests or commits in the GitHub branch after the changes are saved, and the configuration set is re-enabled.
This means that files uploaded to Smartling before any changes to the configuration, will keep using the settings that were in effect when they were uploaded.
Tip: For more information, read our documentation on Modifying Configuration Sets.
Content Parsing
All supported file types can be translated via the GitHub Connector. Each file type is handled differently in Smarting.
Ensure to consult the file's documentation before setting up the configuration set and translating it, so you can better understand the file’s default parsing behavior, and how this behavior can be controlled with directives.
Tip: Directives can be defined for each file type from the Configuration Set.
Visual Context
The GitHub Connector does not automatically generate visual context. However, visual context can be generated by integrating with the Smartling Context Chrome Extension or JS Library. Alternatively, you can always manually upload visual context via the Context dashboard.
File URI vs Namespace
The GitHub Connector is built to work with standard development processes. Multiple developers may work on the copies of the same product code within their respective branches.
The file URL is the file identifier in Smartling and can b used to locate the strings in the file from the Strings View. When pushing files to Smartling from a pull request or commit, the file URI is defined by the connector’s configuration set, and follows the convention configuration set ID + branch name + folder + filename and extension, e.g.:
e6f86b97b8c5/main/localization/app.properties
The namespace, however, is what makes the file and the strings within the file, unique. Because the same file is typically worked on in multiple branches within your repository, the namespace is the file URI without the branch name, e.g.:
e6f86b97b8c5/localization/app.properties
Updating Source Files
After translations are delivered back to GitHub, only changes made to previously translated strings are ingested for translation - saving you time and translation costs.
Furthermore, if the same files are uploaded from a different configuration set or file name, Smartling treats it as a new file and therefore, new strings for translation. SmartMatch can be used to match pre-existing translations in your translation memory - again, saving you time and translation costs. In this scenario, authorization is also required. This can be set to happen automatically with auto-authorize.
Translation Delivery
When set to Pull Request Mode or Single Branch Mode, translations of the file are automatically delivered back to GitHub once the translation Job is complete for all languages. Translation delivery happens when the entire Job is completed, for all languages. This means that if the translation of your file is in progress in Smartling for multiple languages, the translated file will not be delivered until all languages reach the published step.
Note: Alternatively, translations can be manually exported anytime from Smartling to GitHub.
This is the typical journey of how your file is translated when no changes are made to the source content. However, in a busy development environment, it is common for the source content to undergo frequent changes. It is important to understand how the connector behaves when that happens.
When Source File Is Updated
If your source file has been updated while translation is in progress, the updated content in the file will be seen in another Job in Smartling. Depending on how many changes are made with every pull request or commit, this could lead to the content in the file being translated in multiple Jobs in Smartling. This behavior can be controlled when using Pull Request Mode, by adjusting the Job Options setting of the configuration set.
The behavior of the connector does not change, even though it may appear unexpected. Translated files are delivered to GitHub as soon as the Job is completed for all languages. This means that the connector delivers the translated version of the source file when the Job is complete. If there are multiple versions of the source file being translated across multiple Jobs, you will see the same number of translated versions of the file delivered to GitHub.
What Happens In GitHub
To delivery translations in GitHub, 3 events occur:
- The connector creates a translation delivery branch
- Commits the translated files to that delivery branch
- Creates a pull request containing the translations to the watched branch
It is crucial for file delivery that the branch the files are sent to Smartling from still exists in the repository. This is especially important if you choose to set up the connector to watch a feature branch.
Tip: For more information on watched branch options, read our documentation on Branch Strategy.
Important Consideration
It is important to understand how translation delivery may vary depending on if you have made updates to the source file in GitHub while a translation Job for that file is in progress in Smartling.
Smartling only keeps the latest file and delivers that file with the latest published translations by default. This means that you could receive a file with more content than what they submitted in the original job, it may have source content if other things aren't translated, etc.
If you continue to update source files frequently in GitHub, we recommend considering changing the watched branch, or setting the configuration set to On-Demand mode, so files are ingested and delivered manually - giving you more control.
Alternatively, if Pull Request mode is required for your development/localization process, we recommend setting Job Options to add content to an existing Job, and consider enabling Translation Hold in your Configuration Set.
Furthermore, because translations are not delivered until the Job is complete for all languages, prepublish feature is not supported with the GitHub Connector.
Tip: For more information on configuration modes, read our documentation on GitHub Configuration Modes.