GitHub Connector

Setting up your GitHub Connector

This article is for Smartling Account Owners and Project Managers users and GitHub Admin users.

This article will walk you through the following steps to set up your Smartling GitHub Connector:

Setting up your Admin Team in GitHub

GitHub users are associated with GitHub repositories in a configuration set in Smartling. Your GitHub localization team must all have Admin user access in GitHub as we require GitHub's Change a Repository's Settings permission in order to add and remove our webhooks.

To make changes to the Connector configuration, you must stop the Connector in Smartling first, make the change, the restart the Connector. Starting and stopping the Connector in Smartling will install and uninstall the webhooks. 

While it is not possible to change the user associated with a configuration set, you can achieve the same result by disabling and deleting that existing configuration set and creating a new configuration set, while logged into Smartling with the preferred GitHub Admin user account.

More on how to create a configuration sets later in this article.

To create a GitHub Admin user

  1. Go to https://github.com and create an account for the new user. The email address used for your GitHub Admin user should match your Smartling Account Owner/Project Manager user email.
Screenshot_2020-12-16_at_17.30.33.png
  1. Click continue. After the Welcome message, proceed to set up your account.
Screenshot_2020-12-16_at_17.32.08.png3. Verify your email addressScreenshot_2020-12-16_at_17.32.29.png
  1. Go to Settings > Account security and set up two-factor authentication.
    Screenshot_2020-12-16_at_17.37.31.png
  2. Go to Organizations > your Organization name > Teams > New Team and create a team in GitHub for your localization team. You’ll need to be logged in as an Admin user for your organization.
    GitHub-CreateTeam.png
  3. Invite the newly created user to this team.
    GitHub-Invite2Org1.png
  4. Add repositories to be localized to the team
  5. Ensure the team has admin access by selecting Admin from the user role dropdown for each repository.
    GitHub-AddRepoMakeAdmin.png

Setting up a GitHub Project in Smartling

  1. Log into Smartling as an Account Owner/Project Manager
  2. Create a GitHub Connector project type
  3. From within this project, click on the gear icon > Project Settings > GitHub Settings
  4. Next, Authorize Smartling.

Authorizing Smartling

  1. In Smartling, go to your GitHub Connector project
  2. Click on the gear icon > Project Settings > GitHub Settings > Add Set
  3. The first time you click "Add Set" will open the Authorization wizard for you to Authorize the Smartling GitHub Connector.
    • This is required to allow Smartling to monitor your repository.
  4. Next, do one of the following:
    • If you are the owner of the organization, you can authorize the Smartling GitHub Connector from the following wizard: Screenshot_2020-12-17_at_11.20.35.png
    • If you are not the owner of the organization, you will first need to request approval from the organization's owners by clicking Request and Authorize from this wizard:request.png
    • Once an owner has approved the request, the GitHub Connector will be able to access the organization, and the user will be able to see the organization and repository listed in the GitHub Connector settings page in Smartling.
  5. Next, connect the GitHub Connector to your organization's repository.

Repository Setup

  1. In Smartling go to your GitHub Connector project
  2. Click on the gear icon > Project Settings > GitHub Settings
  3. If this is the first time you are connecting Smartling to GitHub, you will need to Authorize Smartling. Once authorized, your Smartling user email will match the GitHub Admin user email and associated Organizations in GitHub.
  4. In the Repository Setup page, choose the following from the dropdown fields:
    • Select your Organization
    • Select your Repository
    • Select the branch you want the GitHub Connector to monitor
      • The default is the main (master) branch
    • Choose which mode you want to set the GitHub Connector to.
    • Click Next.
  5. The Smartling GitHub Connector is now connected. Next, create a configuration set.

Creating a Configuration Set

  1. In Smartling go to your GitHub Connector project
  2. Click on the gear icon > Project Settings > GitHub Settings
  3. Click Add Set to connect Smartling to a repository and create a configuration set
    • If this is the first time you are connecting Smartling to GitHub, you will need to Authorize Smartling and complete the Repository Setup.
  4. Choose the source file type you want the Connector to monitor in the chosen branch.
  5. Under Path, choose the file name you want monitored, the files you want excluded, and where and how the translated files can be found in GitHub.
    • Include Files (required): type the source file name you want the Connector to monitor for pull requests, as seen in GitHub, including the file extension. This can include the folder name e.g., JSON/example_filename.json. Use glob wildcard search (*) to select "any", e.g., **/*.json will return a list of any JSON files in any folder in your chosen branch. The Preview File Output will display matching files from your repo.
    • Translated Files (required): Choose the translated file destination in GitHub from Smartling and the file naming convention. Follow the path as displayed; path/file_name/language. You can use any of the variables listed, or customize each variable.
      • 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 repo, it will be created when the first translation Job is complete.
      • Original file name = the translated fie will have the same name as the source file. To customize this, insert an alternative file name, e.g., my_translated_file.
      • Locale = the translated file name will include the translated locale code. This can be customized in Custom Locale Codes.
      • Original extension = the translated file will include the source file type extension. This is required, do not customize.
    • Exclude Files (optional): type the source file name you want the Connector to exclude from the translation process and not monitor for pull requests, as seen in GitHub, including the file extension. This can include the folder name e.g., JSON/example_filename.json. Use glob wildcard search (*) to select "any", e.g., **/*.json will return a list of any JSON files in any folder in your chosen branch. The Preview File Output will display matching files from your repo.
  6. Click Next
  7. Under Directives, you can add any file directives applicable to your chose source file type.
    • Choose any directive type from the dropdown and under Value, insert the applicable value type.
    • For example under Type = entity_escaping, and Value = TRUE
    • 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, view the strings to see if the content was captured in a placeholder.
    • Add as many directives as you need by using the + icon.
    • You can always add file directives within the source file, however it is recommended to add them to the configuration set to streamline your translation process.
    • For more information on file directives, go to your chosen source file documentation
  8. Click Next
  9. Your configuration set is now created, but remains disabled until you switch it on.
  10. Before you switch on your configuration set, you can choose to enable Custom Locale Codes and Auto-Authorize 
  11. To enable Custom Locale Codes:
    • Click the hyperlinked number 
    • A list of the target languages in your Smartling Project will be displayed, together with the locale code.
    • Enter your preferred custom locale code that will display in the translated file type in GitHub. For example, fr-FR could be customized to fr_FR, fr, or French.
  12. To enable Auto-Authorize:
    • Click the hyperlinked "OFF"
    • Confirm your selection by clicking Yes and Save
    • Enabling this setting will automatically authorize any Jobs created by committed pull requests and start the translation process in the project default workflow.
  13. When you're happy with your configuration set, click the on toggle to enable it.
    • Once you enable the configuration set, the Connector will check your repo for content, upload any files it has been configured to monitor, and create an "INITIAL" Job in your GitHub project.
    • Once enabled, you cannot make any changes to the configuration set.

If you need to update the configuration set to include or exclude certain files, add more directives or custom locale codes, you must first switch it off by clicking the toggle, so it displays "OFF".

Simple Glob Wildcard Explained

* = match any part of file name or folder
** = match any folders (multiple levels)


Simple examples:

/strings/*.properties -> will match any file with .properties extension in the folder /strings/

**/.*properties -> will match any file with the .properties extension in any folder, anywhere

/resources/**/en/*.* will match any file that is in the root folder /resources, in any subfolder as long as the last parent folder is /en/

Was this article helpful?