GitHub Connector Configuration Sets

 

To ensure the right content is sent for translation, the GitHub Connector can be set up to monitor specific file paths within multiple branches and repositories. This is done by creating configuration sets. A configuration set allows you to specify the repository and branch which is connected to the Smartling project, and which specific files should be translated.

Sample Architecture

It is common to set up multiple configuration sets for a single repository in the one Smartling project. However, you can set up multiple configuration sets for multiple repositories in multiple projects. Alternatively, you could connect a single repository to multiple projects, each with different configuration sets, set to monitor different files.

However, if you do decide on this setup, we recommend running a number of test Jobs first, to make sure everything is working as expected. Technical issues may arise if you have two Smartling projects monitoring the same files within the same repository. 

Customization

Extra settings and directives make sure the translation Jobs are created according to your requirements. Multiple configuration sets can be set up within the same Smartling project. They can be directed to different repositories and branches, or even the same one if you need to configure different files for translation or use different settings.

Connection

The GitHub Connector offers two modes of authentication when setting up Configuration Sets: GitHub App (recommended) and OAuth App.

When creating Configuration Sets with OAuth App, it logs in via the same account you are logged into in GitHub when you create that set. If your process doesn't allow for a dedicated user for the GitHub Connector, then your team members must be vigilant when creating configuration sets. They must be logged in as a GitHub Org member/Repo Admin user. Overlooking this may result in multiple configuration sets relying on the permissions from multiple different accounts from the various people who created them.

Elements of a Configuration Set

The following are primary elements of a configuration set. Once the configuration set is successfully created, you can modify it and further customize it with additional settings.

Organization

Your 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. For advice on your branch strategy, read our documentation on Branch Strategy.

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.

 

Integration Type

The integration type is the mode in which the connector should be configured. For more information on GitHub Connector configuration modes, read our documentation on Configuration Modes.

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:

• Upload File Paths: Path of files to be monitored and sent for translation*.
• 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 ensure that translated files are not 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 Path: Path of files that should not be sent for translation*.

*Upload and Exclude paths allow glob wildcards.

Tip: Preview of file output to check if the correct source files will be included in your connector configuration and if the translated file will show up 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 file 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 file 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 what you 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 are working with the same repository, branch, and file paths or 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

Parsing behaviors can be controlled with Smartling file directives. Directives are instructions that tell Smartling how the various elements of a file should be handled and parsed. For example, you can specify which content within the selected files should be translated, or not translated, which placeholder format should be used, which elements in the file should be used as keys etc.

Directives may differ based on the type of file. You can select any of the directives that are available for your chosen file format. These directives can be added inline in the files or configured in the connector settings. The selected directives will then be applied automatically when the files are uploaded to Smartling.

Placeholder directives can cause errors if the value is invalid in the configuration set. Errors include a Job being automatically cancelled. If you decide to configure a placeholder directive, ensure that the value is correct by testing beforehand.

A test could involve inserting placeholders in a resource file, inserting the placeholder directives and value you would like to use in the configuration set within the file, manually upload the file to Smartling, then viewing the strings to see if the content was captured in a placeholder.

For more information about each of the directives and how they work, consult the specific file format's documentation.

Enable Configuration Set - Initial Job

To initiate the GitHub Connector, you need to enable the configuration sets.

Once you enable a configuration set using either the 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.

The creation of this initial Job ensures that the Smartling project stays fully synchronized with your repository.

Do Not Cancel Initial Job

It is important to understand that the purpose of the initial Job is to create content parity between GitHub and Smartling. The content that has already been translated into specific languages in the project can SmartMatch to published, so they don't require additional translation. Only new content is sent for translation, and so moving forward, you only translate what is new.

Cancelling the initial Job only further conflicts the content within the two platforms, which could result in further translation costs. If you cancel the Initial Job, then the next time a Job is created, the initial strings will be added to the new Job.

If the initial Job was accidentally created, never authorized, and subsequently cancelled, the strings from that file will no longer be associated with any Job. When you push that file again, the strings will not be captured and included in a new Job. Instead, they will remain awaiting authorization, outside any Job. As a result, the initial file will never be delivered.

Rather than canceling the Job, if you encounter a mistake in the configuration set, you can simply amend it in the configuration set to rectify the issue.

Modifying a Configuration Set - Disable First

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.

After making the necessary changes, the configuration set can be enabled again. The connector creates an "initial" translation Job each time a configuration set is enabled. Therefore, when you update and re-enable a configuration set, another initial Job will be created specifically for this modified set.

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.

If no new files or updates to existing files are included during the modification of the configuration set, the initial Job will not contain any content for translation and will be automatically cancelled.

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.

Tip: For more information on how you can customize the configuration set, read our documentation on Customize GitHub Connector Configuration Sets.