Setting up your GitHub Connector

This article is for Smartling Account Owners and Project Managers users and GitHub Org member/Repo Admin users.

Create a Connector Project in Smartling

Step one in setting up a Connector in Smartling is always to set up a Connector Project in Smartling. Read about how to create a Project here.

Setting up your Team in GitHub

GitHub's users are associated with GitHub repositories in a configuration set in Smartling.

The GitHub Connector relies on users having admin access to the repository, and a member of the GitHub organization. 

Your GitHub localization team must all have Admin user access to the repository, as we require GitHub's Change a Repository's Settings permission to add and remove our webhooks. 

To modify 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 Org member/Repo Admin user account.

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

To create a GitHub member

1. Follow steps outlined in GitHub's documentation on how to invite members to your organization
   
   • The email address used for your GitHub member user should match the Repo Admin user email.
   • It is important to note that the connector uses OAuth and therefore logs in via the account you are logged into in GitHub whenever you create that set. If multiple members of your teams create 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.
2. Add repositories to be localized to the team
3. Ensure the team has admin access to the repository by selecting Admin from the user role dropdown for each repository.
   

Authorizing Smartling

1. In Smartling, go to your GitHub Connector project
2. Click on the Settings tab > 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:
   • 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:
   • 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 Settings tab > 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 Org member/Repo Admin user email and associated Organizations in GitHub.
4. In the GitHub Settings page, click Add Set and 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.

Create / Edit a Configuration Set

1. Log into GitHub as a GitHub Org member/Repo Admin user.
   • The connector uses OAuth and therefore logs in via the account you are logged into in GitHub whenever you create that set. If multiple members of your teams create configuration sets, they must be logged into 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.
2. In Smartling, go to your GitHub Connector project
3. Click on the Settings tab > GitHub Settings
4. 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.
5. Choose the source file type you want the Connector to monitor in the chosen branch.
6. 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.
7. Click Next
8. 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. 
9. Click Next
10. Your configuration set is now created, but remains disabled until you switch it on.
11. Before you switch on your configuration set, you can choose to enable Custom Locale Codes and Auto-Authorize 
12. 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.
13. 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.
14. When you're done with setting up 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".

Tip: For more information on configuration sets, read our documentation on GitHub Connector Configuration Sets.

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/

Adding a new language

The GitHub Connector only works with files and jobs that it has created. If you'd like to translate to a new language, there are a couple of ways to do this. (Either way, you should prepare to have a new language by considering your Style Guide and Glossary so that they can be ready to add the new language.)

• Option1: Add a language and immediately start the translation of all content in the configured files.
  
  1. Go to the GitHub Connector settings page. Stop the GitHub Connector, then add the language to the Smartling project.
  2. Start the GitHub Connector.
     
     Result: The GitHub Connector will scan the repository as configured, pick up all matching files, and put them into a new job will all project languages, most importantly, the "new language" will now have all the files which can then be authorized.
     
     Note: Any strings in the files that have already been picked up for translation for other languages will also be included in this job. Therefore, it's not guaranteed to be a job just for the new language.
  
  
  The GitHub Connector will continue to operate as normal, picking up any new pull requests or commits, and creating new jobs for all languages.
  
  
  
• Option 2: Add a language and wait for the next pull request, or commit to start translation of all content in the configured files. If you don't want to force the start of the translation of the new language, you can just add the language to the Smartling project. The next pull request or commit will automatically pick up the changed files, and any strings within those files will be included for the new language. However, not all files for the project will be picked up - only files that are changing in the pull request or commit. This means that it can take time to pick up all the files.
  
  Note: If at any time the GitHub Connector is restarted, it will create an INITIAL file, and it can pick up all matching files for all languages as described in step 1 above. If you don't want to translate everything, you can just cancel that job and continue to wait for new pull requests or commits.