This reference guide is designed for users who are new to GitHub or new to working with Smartling's GitHub Connector. It provides definitions of key terms you'll encounter when setting up and using the connector.
GitHub Terms
Branch
A branch is a separate workspace within a repository where developers can make changes without affecting the live version of the code. A branch functions as a copy of the project where new features or fixes can be developed independently. Once changes are ready, they can be merged back into the main live version.
Commit
A commit is a saved snapshot of changes made to files. Each commit includes a description of what was changed, creating a historical record of all updates over time. This allows teams to track who changed what and when, and to restore previous versions if needed.
You can think of a commit like saving your work or pressing the save button in a word processor. Each commit saves any changes to the current branch, and that complete history of changes is preserved indefinitely. If a change produces undesirable results, it’s easy to revert to a previous version (or commit).
You can make multiple commits on a branch before merging it into another branch, which essentially combines the changes you saved (i.e., committed) to one branch into another branch, which is often the main branch or a branch where updates are collected until they are ready to be merged into the live production branch.
Feature Branch
This is just another name for a branch (see above). The naming convention for branches often follows a pattern like this. Please note, however, that these are just common examples and each company may organize its repository differently.
- Main - The latest production branch, which contains features and code released to customers.
- Develop - Where active development takes place. Usually, any new features or fixes will be merged back here before being included in a release.
- Release - A space to collect new features and hotfixes. Once the desired set of changes has accumulated here, it may be merged into Main or some equivalent for release to customers.
- Feature - A branch where development on a new feature is concentrated. There may be sub-branches that merge back into the new feature before the finished item is incorporated into Develop or Release.
GitHub
GitHub is a web-based platform for hosting, managing, and collaborating on code. It uses a version control system called Git to track changes over time. As an online version control system, GitHub enables developers to work together seamlessly on projects, regardless of location.
Main Branch
The main branch is the primary branch in a code repository that contains the production version of an application. All other branches are typically created from the main branch, and finished work is merged back into it. This branch represents the current stable state, or "live version," of a project.
Merge
Merging is the process of combining changes from one branch into another. This usually happens after a pull request is reviewed and approved, allowing updates from a feature branch to be integrated into the main branch.
Pull Request (PR)
A pull request is a formal request to merge changes from one branch into another. It allows team members to review, discuss, and approve updates before they are merged into the target branch, which is often the main branch. A pull request may contain many commits and remain open for anywhere from a few hours to several weeks or months while work is done on a new feature or a fix.
Repository
A repository (or "repo") is a project space in GitHub that stores all files, code, and version history for a specific project. Think of it as a central folder where all your website or application files live, along with a complete history of every change made to those files. Within a repository, you have all of the branches (versions) of your files and code, as well as the whole history of changes made within that repository.
Commit Status
A commit status is an automated verification process that runs when a pull request is opened. It ensures that code meets defined quality or build requirements before being merged. The GitHub Connector sets commit statuses on the pull requests it monitors to verify translation and translation delivery status. In addition, commit statuses can be referenced in GitHub via branch protection rules. These rules can prevent pull requests from being merged until translations are complete and included in the pull request.
Version Control System
A version control system tracks and manages changes to files over time. It lets you see who changed what and when, and restore previous versions if needed. Git is the version control system that GitHub is built on, enabling teams to collaborate on projects while maintaining a complete history of changes.
Connector-related terms
Authorization
Authorization refers to the approval required before translation work can begin on a job. When the GitHub Connector creates a translation job, that job must be authorized before the translation process begins. Until authorization occurs, strings in the job have the status "awaiting authorization." The connector can be configured to automatically authorize all translation jobs, or this setting can be disabled so jobs must be authorized manually from the Smartling dashboard.
Commit Grouping
Commit grouping is a configuration setting that controls how files are organized and pushed back to your repository in translation delivery pull requests. For example, the Single Commit setting pushes all translated files to GitHub in one commit. In contrast, the Per Locale setting will group all files for each locale into a separate commit.
Configuration Set
Configuration sets are the core mechanism for controlling how the GitHub Connector monitors and translates your content. A configuration set defines which repository, branch, and files the connector should monitor, along with the integration mode and file path specifications. Each configuration set represents a distinct set of rules for how content synchronizes between GitHub and Smartling.
Directive
A file directive is a special instruction that tells Smartling how elements within a file should be handled and parsed into translatable units called strings. Directives define which text should be translated or excluded, which content should be captured as non-translatable placeholders, and which elements should serve as keys or other string metadata. These instructions ensure your files are processed correctly for translation.
Early Delivery
Early Delivery is a feature that allows translations to be delivered to GitHub before a job is fully completed. It requires enabling prepublish on workflow steps and automatically triggers an early translation delivery pull request when all strings in the job are prepublished. Early Delivery supports both Pull Request and Single Branch modes and provides two separate pushes: an Early Delivery push with initial translations and a Final Delivery push with completed translations.
Initial Job
Whenever a configuration set is enabled in Pull Request or Single Branch mode, Smartling automatically syncs content from GitHub by creating an initial job, identified with "INITIAL" in the job name. This job includes all repository files that match the configuration set criteria and ensures your Smartling project is synchronized with your GitHub repository.
Always authorize this initial job and allow it to complete. This is essential for ensuring that Smartling and GitHub are fully synchronized.
Initial jobs should not be canceled, as doing so can create translation inconsistencies and result in unnecessary costs. If the job includes content that was already translated into certain target languages, those strings will SmartMatch when the job is authorized and will not incur additional translation costs. Only new or updated content will need to be translated. If everything is already in sync, the job will contain no content and can safely be ignored.
Integration Type/Mode
The integration type (also referred to as a "mode") determines when and how content is uploaded to Smartling for translation. Depending on your team's development process, the connector can ingest content when a pull request is opened, when a commit is made to a watched branch, or only when triggered manually. The three integration modes are Pull Request Mode, Single Branch Mode, and On-Demand Mode.
Locale Code
A locale code is a combination of characters that identifies a specific language and region combination. Each language you configure in a Smartling project has a display name shown in the dashboard and an underlying locale code used by the Smartling TMS. For example, "en-US" represents English (United States) while "fr-FR" represents French (France). You can find a complete list of Smartling-supported languages and locale codes in our Supported Languages article.
Manual Export
Manual export refers to manually sending translations from Smartling to GitHub instead of relying on automated delivery. Although the connector supports fully automated delivery, manual export provides the flexibility to trigger translation delivery on an ad-hoc basis when needed.
A manual export will cause the GitHub Connector to scan the repository, reload all files that match your configuration into Smartling, and immediately push translations for those files back to GitHub. These types of exports are a good way to ensure updates made to published translations are synchronized back to GitHub. These exports can also be scheduled (see Scheduled Tasks).
On-Demand Mode
On-Demand Mode is an integration type that provides full manual control over when your content is synchronized between Smartling and GitHub. Unlike other modes, it does not monitor pull requests or commits. Instead, it is triggered manually in Smartling by your teams. This includes an action to ingest content into Smartling and a separate action to export translations back to GitHub.
Pull Request Mode
Pull Request Mode is an integration type in which the connector monitors a selected branch in the repository, looking for pull requests made against that branch as triggers. It checks each pull request for files matching the configured paths that have new or updated content needing translation and then creates translation jobs in Smartling. Once a translation job is created, the commit(s) in the pull request that contain files for translation have a commit status set to reflect that the files from the commit(s) are being translated.
Scheduled Task
Scheduled Tasks allow you to automate actions that would otherwise require manual triggering in the Smartling dashboard, such as manual exports. This feature lets you schedule routine tasks at regular intervals. Currently, this feature only supports Translation Export tasks, with support for additional task types planned for future releases.
Single Branch Mode
Single Branch Mode is an integration type in which the connector monitors the selected branch in your repository, using commits to that branch as triggers. It checks each commit for files matching the configured paths that have new or updated content needing translation and then creates translation jobs in Smartling.
Translation Delivery PR
A translation delivery pull request is how translated content is returned to GitHub. When the connector delivers translations, it opens a separate branch in your repository that includes the translated content in a translation delivery pull request, which can then be reviewed and merged into the appropriate branch. In Pull Request mode, the translation delivery PR is opened against the feature branch. In Single Branch and On-Demand modes, the translation delivery PR is opened against the monitored branch.
Translation Hold
Translation Hold is a feature available only in Pull Request Mode that helps manage when translation work begins. When enabled, it automatically applies a "hold" label to GitHub pull requests, which prevents the creation of Smartling translation jobs until the label is manually removed by your team.
Monitored Branch
The monitored branch is the branch that the connector watches for new or changed translatable content. When you create a configuration set, you specify which branch the connector should monitor. Common choices include feature branches, development branches, or the main branch.