Smartling’s GitHub Connector lets you integrate translation directly into your existing developer workflows. It is designed to work seamlessly with standard development practices, supporting multiple developers working on the same product code within their respective branches.
The connector enables you to synchronize your GitHub repositories with Smartling and is highly customizable, offering a variety of modes and settings that control when and how your GitHub content is ingested into Smartling for translation, as well as when and how translated content is delivered back to GitHub. Because the connector is hosted in Smartling, all configurations are managed directly within the Smartling platform.
New to GitHub or want a quick reference? Check out our GitHub Connector terminology reference sheet.
How it 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. Multiple configuration sets can be created within a single Smartling project, each targeting different repositories or files.
The typical connector flow follows three main steps:
- Monitor for changes: The connector monitors the selected branch in your repository, using pull requests or commits as triggers. It checks each pull request or commit for files matching the configured paths that have new or updated content needing translation.
- Send content to Smartling: When translatable content is detected, the connector automatically uploads files and creates translation jobs in Smartling. Depending on your configuration, jobs can be automatically or manually authorized for translation.
- Deliver translations back to GitHub: Once translations are complete, the connector pushes them back to your repository in a separate translation delivery branch, which can then be merged into the monitored branch.
Getting started
Before you begin using the GitHub Connector, we recommend reviewing the following materials to understand what's required for setup, the default connector behavior, and available customization options. Taking time to plan your approach will help ensure the connector aligns with your team's development process.
Authentication
Before you can use the GitHub Connector, you'll need to authenticate. This involves two main steps:
- Create a GitHub connector project in Smartling
- Authenticate using the Smartling GitHub App (recommended approach)
The Smartling GitHub App provides improved security and performance compared to the legacy OAuth App. If your project contains older configuration sets set up with the legacy OAuth App, we recommend switching to the Smartling GitHub App via the migration process detailed in the resources linked below.
Resources
- Types of Authentication for the GitHub Connector
- Setting Up the GitHub Connector with GitHub App
- Migrating from OAuth App to GitHub App
Configuration sets
After you’ve successfully authorized the Smartling GitHub app, you can begin creating configuration sets. A configuration set is a group of settings that control which repository and branch to monitor, when content should be sent to Smartling for translation, which file types to translate, how translations are delivered back to GitHub, which languages to translate into, and more. This is where you can customize the connector’s default behavior.
You can create multiple configuration sets within a single project, allowing you to integrate repositories targeting different branches or files, each configured with its own connector settings.
Integration types
The connector offers three integration modes to synchronize your GitHub repositories with Smartling. Depending on your team’s development workflow, you can configure Smartling to ingest content when a pull request is opened or when a commit is made to monitored branches. A manual mode is also available that allows synchronization with GitHub on demand.
Pull Request Mode: Monitors pull requests and draft pull requests, and uploads files if changes have been made to configured file types and paths. This ensures translations happen as part of your standard development process and that translated files are added to the pull request before it is merged.
Single Branch Mode: Monitors commits to a specific branch and captures any changes made to configured file types. This mode is ideal for teams that prefer to add translations to features after their development process is underway or completed.
On-Demand Mode: Synchronization between Smartling and GitHub is not triggered by activity and instead is kicked off by your teams. This mode lacks any automation, but gives you complete control over when content is ingested for translation and delivered back to GitHub.
Learn more: GitHub Configuration Modes: Pull Request, Single Branch, On-Demand and How to Decide Which Branch the GitHub Connector Should Monitor.
What you can customize
Configuration sets give you granular control over the connector's behavior, including:
-
Source Paths
Define which files and folders in your repository to monitor for translatable content. -
File Types
Specify which file types to translate and how they should be parsed, meaning which elements of the file are uploaded as translatable text, which are captured as non-translatable placeholders, and which are included as string metadata. This parsing behavior determines how the file content is ingested into Smartling as translatable units called strings. You can control parsing behavior using file directives. Learn more about file directives. -
GitHub Activity Processing
Control when the connector reads and processes changes in your repository. For example, in Pull Request Mode, you can configure the connector to watch only standard pull requests and ignore draft pull requests, or apply a hold label to pull requests in GitHub, blocking job creation until the label is manually removed. Learn more. -
Job Creation
Configure how and when translation jobs are created in Smartling, including which locales to translate into and whether jobs are authorized automatically. Learn more. -
Translation Delivery
Determine how and when translations are delivered back to GitHub, either after job completion (default) or earlier using Early Delivery. You can control commit grouping (how commits are pushed back to GitHub in translation delivery pull requests), configure custom locale codes to use in translation paths, and specify behavior when no translation is available (return either the original source string or an empty string). You can also optionally include PR reviewers in the translation pull request when using Pull Request Mode. Learn more.
Additionally, it is now possible to turn off automatic delivery of translations to GitHub and instead rely on translation exports (manual or via Scheduled Tasks).
For a complete, detailed explanation of all settings and customization options, refer to the resources below.
Resources
Understanding files and content
Supported file types
All supported file types fix can be translated via the GitHub Connector. Each file type is handled differently in Smartling, so it's important to consult the file's documentation before setting up your configuration set. This helps you understand the file's default parsing behavior and how to control it with directives, which can be defined for each file type in your configuration set.
File URIs vs. namespaces
URIs
When the GitHub Connector ingests content for translation, it uploads the content as a file. Each uploaded file is assigned a file URI, which serves as the file identifier in Smartling and can be used to locate strings within that file from the Strings View.
The file URI is defined by the configuration set and follows this convention:configuration set ID + branch name + path + filename and extension
Example: e6f86b97b8c5/main/localization/app.properties
Namespaces
The file namespace is an additional piece of metadata for the file. Because the same file is typically worked on in multiple branches, the namespace is the file URI without the branch name.
Example: e6f86b97b8c5/localization/app.properties
Namespaces are important for string deduplication. If two strings have the same text and variant and come from files with the same namespace, they are considered the same string in Smartling and will not be duplicated.
How strings are shared across files
Here is an example from a GitHub Connector project. A source string with the text "addUser" exists in two different files. Because the string variant and file namespaces are the same, Smartling treats this as one string shared across both files. Whenever either file is delivered back to GitHub, the same translation is used.
Updating source files
Making changes to translatable content
After translations are delivered back to GitHub, only changes made to previously translated strings are ingested for translation, saving you time and translation costs.
If the same files are uploaded from a different configuration set, the files will be assigned a different file URI and namespace (using the configuration set ID). As a result, Smartling will treat it as a new file and therefore new strings for translation.
Example scenario:
-
Configuration Set A targets the
app.propertiesfile in the localization folder. The file in Smartling is assigned the URI:e6f86b97b8c5/main/localization/app.properties. All strings in this file are tied to this file. -
Another configuration set, Configuration Set B, is created and targets the same
app.propertiesfile. Smartling treats the strings in this file as unique because the file namespace is different (due to the different configuration set ID). If the strings from Configuration Set A are already published, any translations saved to your translation memory can be leveraged via SmartMatch and so you do not need to pay to have the same text translated twice.For strings to SmartMatch, they must first be authorized for translation. You can check how many strings in a job are expected to SmartMatch by checking the cost estimate.
Here is an example from a GitHub Connector project. The source string "Add a user" exists in three different files.
- Two files share the same namespace, so the string is shared. (You can tell a string is shared because the file URI is blue with a caret icon. Click the caret to see which files the string is shared across).
- The third file has a different namespace (uploaded by a different configuration set), so the string is unique.
- If one of the strings is translated, published, and saved to your translation memory, the other string does not need to be re-translated. If SmartMatch is enabled in your project, it can leverage the translation from the translation memory and move directly to the published step, saving time and money.
Making changes to non-translatable content
The connector not only monitors changes to translatable content, but also detects changes to non-translatable content, such as removing or reordering source strings or altering the source file structure. When these changes occur, the connector reuploads the source file to Smartling to ensure synchronization. When translations are delivered, the translated files are pushed back to GitHub with the same structural changes applied, maintaining synchronization between Smartling and GitHub.
Configuration changes
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 according to the configuration set associated with that version of the file.
Important: If you make changes to your configuration set, those changes will only affect files uploaded to Smartling as a result of pull requests or commits after the changes are saved and the configuration set is re-enabled. Files uploaded before configuration changes will continue using the settings that were in effect when they were uploaded.
Learn more: GitHub Connector Configuration Sets.
Translation delivery
The GitHub Connector offers flexible options for delivering translations back to your GitHub repository.
Default delivery behavior
By default, translation delivery is automatically triggered upon job completion (except in On-Demand mode, which is fully manual). This means as soon as a translation job is complete in Smartling, translations are automatically delivered back to GitHub.
Translations are delivered to GitHub in a separate branch that follows a standard naming convention, making it clear that the branch is from the Smartling Connector. This branch can then be merged into the monitored branch.
You can disable the default automatic translation delivery for a configuration set under Translation Delivery settings. Disabling automatic delivery prevents translation pull requests from being generated in GitHub and requires you to use manual or scheduled translation exports instead.
Additional delivery options
Early delivery
You can receive translations before a job is completed by enabling Early Delivery on a configuration set. This feature allows you to access translations as soon as they are prepublished, rather than waiting for the entire job to complete and for all strings to reach the final published step. See Get Translations Before Job Completion with Early Delivery.
Manual export
You can manually export translations at any time. This feature is available in all configuration modes and is essential for translation delivery when using On-Demand mode, since translations are not exported automatically in that mode fix. See Manually Export Translation to GitHub.
Manual exports can be made against any branch, not just the monitored branch. This is useful for ensuring a new branch has all the latest translations, such as a branch used for a hotfix, nightly build or a planned release. During a manual export, the GitHub Connector scans the selected branch and uploads any files matching your configuration set. Those files are processed and instantly pushed back out with their available translations.
Scheduled export
Instead of logging in and manually triggering an export from the Smartling dashboard, you can configure a scheduled task for translation export. This pushes translated files on a predefined schedule, ensuring that translations in Smartling are synchronized with those in GitHub automatically on a set schedule. Scheduled exports are particularly useful if you choose to disable automatic translation delivery. See GitHub Connector Scheduled Tasks.
Similar to manual exports, scheduled translation exports can be pointed to any branch, allowing the aforementioned flexibility in ensuring that any branch has the latest translations.
How the connector delivers translations
Translation delivery includes three events:
- The connector creates a translation delivery branch.
- The connector commits the translated files to the delivery branch.
- For configuration sets created after February 2025, by default, the connector uses the Per Locale strategy, meaning it creates one commit per target locale containing all translated files for that locale.
- For configuration sets created before February 2025, the default strategy is Per File and Locale, meaning the connector creates a separate commit for each file for each target locale.
- You can modify this behavior using the Commit Grouping setting.
- The connector creates a pull request containing the translations against the monitored branch.
For successful file delivery, the branch from which the files were sent to Smartling must still exist in the repository. This is especially critical if the connector is configured to watch a feature branch.
Tip: For more information on monitored branch options, read our documentation on Branch Strategy.
Working with frequently updated files
In busy development environments, source content often undergoes frequent changes. Understanding how the connector behaves when this happens is important for smooth localization processes.
When source files are updated during translation
If your source file is updated while translation is in progress, the updated content will appear in another job in Smartling. Depending on how many changes are made with every pull request or commit, this could lead to content being translated across multiple jobs. This behavior can be controlled when using Pull Request Mode by adjusting the Job Options setting in your configuration set.
The connector's default behavior remains consistent: translated files are delivered to GitHub as soon as the job is completed for all languages. If there are multiple versions of the source file being translated across multiple jobs, you will see the same number of translated versions delivered to GitHub.
Smartling only keeps the latest file and delivers that file with the latest published translations by default. This means you could receive a file with more content than what was submitted in the original job.
Recommendations for frequently updated files
If you continue to update source files frequently in GitHub, consider:
- Changing the monitored branch: Use a more stable branch that changes less frequently
- Setting the configuration set to On-Demand mode: This allows you to ingest and deliver files manually, giving you more control
- Adjusting Job Options: In Pull Request mode, set Job Options to add content to an existing job and consider enabling Translation Hold
- Using Early Delivery: Get pre-published translations delivered before the entire job is complete
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.
Monitor activity in your project
You can view an overview of GitHub activity within your GitHub Connector project in Smartling from the GitHub Activity page. Use this page to see pull requests and commits that do or do not initiate translation jobs. It provides direct links to GitHub and a variety of filters, giving you a clear view of all activity happening in your project. See Monitor GitHub Activity in Smartling.
Managing languages and updates
Adding new target languages
By default, configuration sets automatically include all enabled target languages in your project. When you add a new target language to the project, any enabled configuration sets using this default setting will create translation jobs that include the new language the next time translation is triggered (e.g., when a new pull request is opened or a new commit is made).
If you've customized a configuration set to include only specific target languages, new project languages will not be automatically added to that configuration set. You'll need to manually edit the configuration set's Locale Management setting to enable the new language.
Learn more: Adding a New Language to the GitHub Connector.
Updating existing translations
If you need to update translations in a job that has already been completed, several options are available for delivering the updated translations back to GitHub.
Learn more: Updating Translations with the GitHub Connector.