GitHub Connector Configuration Sets

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.

You can create multiple configuration sets within a single Smartling project to:

• Monitor different branches within the same repository
• Connect multiple repositories to one project
• Apply different translation settings to different file sets

If you connect a single repository to multiple Smartling projects monitoring the same files, technical issues may arise. We recommend running test jobs first to ensure everything works as expected.

How to create and view configuration sets

1. Within your GitHub Connector project, navigate to the Settings tab > GitHub Settings.
2. You will see a list of existing configuration sets. Click Create Configuration to create a new set.

Search & filters

From the configuration sets list, you can search for configuration sets by name or filter them by integration type or status.

Sorting 

At the top right of the configuration sets list, you can sort configuration sets by Status, Modified Date, or Repo. Sorting by Status in ascending order will display configuration sets with issues first (Error / Warning / Needs Attention), followed by Enabled, and then Disabled. Sorting by Repo arranges configuration sets alphabetically by the repository name.

 

Configuration sets connected to a large repository will display a Large repository label. This indicates that actions such as initial job creation and translation delivery may take 30 minutes or longer to process. Interrupting these actions by stopping the connector can cause delays.

Primary elements of a configuration set

When creating a configuration set, you'll need to specify the following key elements:

Authentication method

The GitHub Connector offers two authentication modes when creating a new configuration set.

• GitHub App (recommended)
• OAuth App

Repository setup

Organization 

Your organization will be pre-populated if you selected GitHub App authentication mode. We highly recommend always creating new configuration sets using this authentication method.

If you selected OAuth, choose the GitHub organization that your Admin user is a member of.

Repository

The repository within the organization that contains the branches with content for translation.

Branch

The branch that contains content for translation. This is also referred to as the "monitored branch," meaning it is the branch that will be monitored by the connector. For guidance on selecting the right branch, see How to Decide Which Branch the GitHub Connector Should Monitor. 

Note: Branch names must not begin with "Smartling" as the connector interprets branches starting with "smartling-" as self-created translation branches and will not monitor changes in them.

Integration type

The integration type is the mode that determines when content is uploaded to Smartling for translation. Depending on your team's processes, you may want the connector to ingest content when a pull request is opened, when a commit is made, or only when triggered manually.  For more information on the different configuration modes, read our documentation on GitHub Configuration Modes. 

Configuration set name

Add a name for the configuration set. The default name follows the format: repository name - integration type. We recommend selecting a name that is relevant and easily recognizable to your team. 

File types

This is where you specify which files the connector should ingest for translation. Select a supported file type from the drop-down menu.

File delivery modes for multilingual file types

When using a multilingual file type, such as String Catalog (XC Strings) files, you can choose how translated files are delivered back to GitHub. The File Delivery Mode determines whether translations are returned as a single multilingual file or as separate files per locale, and whether the original source file is replaced.

Overwrite Source

In Overwrite Source mode, the original source file is replaced with a multilingual version of the file that contains translations for all configured target locales.

• The original file is overwritten with a multilingual version of the translated file.
• The translated file is delivered to the same location as the source file. 
• It is not possible to modify the translated file path.

Use this option when your system expects a single file that contains all languages and can safely replace the source file.

Multilingual Download

In Multilingual Download mode, source files are downloaded as a single multilingual file that includes translations for all configured target locales and delivered to your specified target path.

• The translated file contains all translations for all locales in one file.
• The {locale} variable cannot be used in the translated file path because the translated file is not specific to one locale. 
• Unlike Overwrite Source mode, you can define a custom translated file path because the original source file is not overwritten.

Use this option when your system supports multilingual files but you do not want to overwrite the original source file.

Single Locale

In Single Locale mode, one translated file is delivered for each configured target locale. 

• A separate file is generated for each target locale.
• Each translated file contains translations for only that locale.
• The {locale} variable can be used in the translated file path, allowing locale codes to be included in file names if desired.

Use this option when your system requires individual, locale-specific files or when translations must be stored or deployed separately by locale.

File paths

File paths define the location of the files the connector should monitor, exclude, and deliver translated files to. If you are creating a new configuration set, choose one file path to begin with. If your branch contains multiple different file types that you intend to translate, you can define additional file types at a later stage, once the configuration set has been created.

The key fields are:

• Include files (upload file paths): Path of files to be monitored and sent for translation*.
• Translated files (translation path): File path and naming pattern for completed translations. This is the location that you want the translated files to be sent to when they are exported back to your repository. Ensure that the path for the translated files is different from the source path to prevent translated files from being sent for translation. 
  • Translation Paths support a negative look behind /../ to remove the previous part of a path. This can be used multiple times. For example, /../../../ would strip out the previous three levels of a path. 
• Exclude files (exclude path): Path of files that should not be sent for translation*. Multiple paths are supported by using the + icon to include additional path fields. 

*Upload and Exclude paths allow glob wildcards.

Tip: Check the file output preview to confirm that the correct source files are included and that the translation files appear in the correct format.

Translation path discrepancies

The configuration information that exists at the time when a file is uploaded to Smartling from a pull request or commit is retained and associated with that specific version of the file. This configuration is utilized when delivering the file.

Translations may not be delivered to the file path defined in the current configuration if the configuration set has been modified. Any changes made to the configuration will only take effect for new pull requests or commits, as well as files that are uploaded after the configuration is saved. In other words, the updated configuration will be applied to future interactions and files, while the previously uploaded files will continue to use the configuration settings they were initially associated with.

Translation path variables

1. {original_path}: the translated file will be sent to the same location as where the source file was sent from. This can be customized to a specific folder name. If the folder name does not already exist in your repository, it will be created when the first translation job is complete.
2. {original_filename}: the translated file will have the same name as the source file. To customize this, insert an alternative file name, e.g., my_translated_file.
3. {locale}: the translated file name will include the translated locale code. This can be customized in Custom Locale Codes.
4. {original_extension}: the translated file will include the source file type extension. This is required, do not customize.

Locale Replacement

This search and replace feature allows you to specify which text in your source paths should be detected as source locale codes, which will then be automatically replaced with target locale codes in your translated paths. This feature can be enabled when setting up a new configuration set or modifying an existing one.

To enable this feature: 

1. Under Paths, select the checkbox next to Locale Replacement.
2. A new field called Source Locale Code(s) will appear.
3. Specify the locale codes to replace in source paths. Typically, this will be the source locale code (e.g., en), but it can be any text string used to identify source material, such as “source,” “intl,” “src,” etc. Source locale codes can be wrapped in any combination of the following permitted characters: / . : - _ ( ) [ ] { } ! |
   • If no wrapping characters are specified, each character will be searched for in a pair around your locale codes, e.g., /en/, .en., :en:, etc. 
4. Press enter to save. You can enter and save multiple source locale code formats. 

By default, the connector uses the Smartling target locale codes from the project. If you define custom locale codes, those custom codes will be used instead for the replacement. 
 

Important considerations when using Locale Replacement

Source file detection 

The connector uses exact matching to find source files based on your input in the Source Locale Code(s) field. If the connector does not find an exact match in the file path, it will not upload the file to Smartling for translation. You can use the GitHub Activity tab in your Smartling project to see which source files have been uploaded by the connector and which have been skipped.

Example:
Repository contains the source files
File 1- /files/en/main/strings.xml
File 2 - /files/en-US/main/strings.xml

Source Locale Code(s) specified for Locale Replacement
en or /en/

Result
Only File 1 will be uploaded to Smartling for translation, the connector will skip File 2. 

Option
If you want both File 1 and File 2 to be uploaded for translation you would need to add en-US or /en-US/ to the Source Locale Code(s) field. 
 

File overwriting

When using Locale Replacement mode, please be aware that translation delivery paths can overwrite one another. This is more likely when multiple source locale codes are used. We recommend reviewing your configuration to avoid any unintended overwriting.

Example:
Repository contains the source files
/file/en/android/strings.xml
/file/en-US/android/strings.xml

Source Locale Code(s) specified for Locale Replacement 
en and en-US

Translation delivery path
/{original_path}/{original_filename}.{original_extension}

Delivered translation files for de-DE
/file/de-DE/android/strings.xml
/file/de-DE/android/strings.xml

Since the translation paths are the same, the translated files will overwrite each other each time one is delivered to GitHub. The GitHub Connector will detect this potential overwriting when both files are part of the same job and will interrupt the delivery of both files. You can check the GitHub Activity Tab in your project to see which translated files have been successfully delivered back to your repository and which have been interrupted.

Detecting file overwriting becomes more challenging when multiple jobs or configuration sets work within the same repository, branch, source paths, or file types. We cannot guarantee that file overwriting will not occur, so be sure to double-check your repository structure and configuration sets to ensure that unique file paths are not reduced to duplicate file paths when using Locale Replacement.

Directives

A 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.

Directives vary by file type. You can select any directives available for your chosen file format. Directives can be added to a configuration set so they are automatically applied when files are uploaded to Smartling (as pictured above), or they can be added inline, directly within the files themselves.

Placeholder directives can cause errors if the value in the configuration set is invalid, which may result in a job being automatically canceled. If you choose to configure a placeholder directive, make sure the value is correct by testing it beforehand.

A simple test might involve inserting placeholders into a resource file, adding the desired placeholder directive inline within the file, manually uploading the file to Smartling, and then reviewing the strings to confirm that the content was correctly captured as a placeholder.

For more information about each directive and how it works, consult the documentation for the specific file format.

Additional customization options

After creating a configuration set, you can optionally configure additional settings. For more details, see Customize GitHub Connector Configuration Sets.

Enabling a configuration set

Once you have created a configuration set and configured any custom settings, you need to enable the configuration set to activate the connector. The connector only functions when configuration sets are enabled. If a configuration set is disabled, the connector will not monitor files or create translation jobs.

To enable a configuration set, navigate to your GitHub Connector project > Settings tab > Github Settings. Click the ellipsis menu under Actions and choose Enable.
 

Once you enable a configuration set using either Pull Request or Single Branch mode, Smartling will automatically generate an initial translation job. This job includes all files from your repository that meet the criteria defined in the configuration set.

Do not cancel the initial job. Authorization and completion of the initial job is critical to ensuring that the Smartling project stays fully synchronized with your repository.

Importance of completing initial jobs

The initial job ensures your GitHub repository and Smartling project are synchronized. It includes all files that match the configuration set and is automatically created when a configuration set is enabled in Pull Request or Single Branch mode. These jobs are identified by “INITIAL” in the job name. Always authorize the initial job.

Do not cancel initial jobs. Cancelling initial jobs can create translation inconsistencies and lead to unnecessary costs. If the job contains any content that was already translated, the strings can SmartMatch when the job is authorized, so only new or updated content requires translation. You can check the job's cost estimate to see how many strings are expected to SmartMatch. If the repository is fully in sync, the job may contain no content, in which case it will be automatically canceled and can be safely ignored.

If you encounter a mistake in the configuration set, rather than canceling the initial job, you can disable the configuration set, make your edits, and re-enable it to correct the issue.

Modifying or disabling a configuration set 

To make any changes to an existing configuration set, you need to disable it first. Once disabled, you can proceed with making the desired updates.

To prevent any issues arising from the creation of this initial job, it is recommended to wait until all ongoing jobs are completed before modifying a configuration set.

To disable a configuration set, navigate to your GitHub Connector project > Settings tab > GitHub Settings. Click the ellipsis menu under Actions and choose Disable. 

After making the necessary changes, the configuration set can be enabled again.

Note: GitHub has "rate limits", which means that their API stops processing and rejects any requests for a while if too many requests are performed for a period of time. If you disable and enable a configuration set multiple times in a short period, the rate limit could be hit and this can prevent the enabling of a configuration set. To resolve this, we recommend waiting for a short period before disabling/enabling a configuration set.

For more information on how you can customize configuration sets, see our article on Customize GitHub Connector Configuration Sets. 

Unable to disable a configuration set

The most common reason that a configuration set cannot be disabled is that permissions on the service user powering the connector have been altered. The OAuth app requires a GitHub user with Admin permissions in the repository you are connecting to. 

The OAuth app will not start if the necessary permissions are not in place. If those permissions are modified after the connector is started, you will experience unexpected behavior, such as not being able to shut down the connector. 

One frequent error is that the connector cannot find and remove the webhooks used to send activity from GitHub to the connector.

To fix this issue and other errors, restore the correct permissions to the GitHub user. 

Note: This issue only impacts configuration sets using OAuth authentication. To migrate to using our GitHub App, which does not require Admin permissions, you can follow our documentation on this simple process.