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
- Setting up a GitHub Project in Smartling
- Authorizing Smartling
- Repository Setup
- Creating a Configuration Set
- Adding a new language
- Mapping custom locale codes to a configuration
Setting up your Admin Team in GitHub
GitHub's 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 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 Admin user account.
More on how to create a configuration sets later in this article.
To create a GitHub Admin user
- 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.
- 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 into GitHub as an Admin user and not any other user role they may use in GitHub. Overlooking this may result in multiple configuration sets relying on the permissions from multiple different accounts from the various people who created them.
- Click continue. After the Welcome message, proceed to set up your account.
- Go to Settings > Account security and set up two-factor authentication.
- 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.
- Invite the newly created user to this team.
- Add repositories to be localized to the team
- Ensure the team has admin access by selecting Admin from the user role dropdown for each repository.
Setting up a GitHub Project in Smartling
- Log into Smartling as an Account Owner/Project Manager
- Create a GitHub Connector project type
- From within this project, click on the gear icon > Project Settings > GitHub Settings
- Next, Authorize Smartling.
- In Smartling, go to your GitHub Connector project
- Click on the gear icon > Project Settings > GitHub Settings > Add Set
- 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.
- 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.
- Next, connect the GitHub Connector to your organization's repository.
- In Smartling, go to your GitHub Connector project
- Click on the gear icon > Project Settings > GitHub Settings
- 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.
- 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.
- The Smartling GitHub Connector is now connected. Next, create a configuration set.
Creating a Configuration Set
- Log into GitHub as an 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 as an Admin user and not any other user role they may use in GitHub. Overlooking this may result in multiple configuration sets relying on the permissions from multiple different accounts from the various people who created them.
- In Smartling go to your GitHub Connector project
- Click on the gear icon > Project Settings > GitHub Settings
- Click Add Set to connect Smartling to a repository and create a configuration set
- Choose the source file type you want the Connector to monitor in the chosen branch.
- 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.
- Click Next
- 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.
- Click Next
- Your configuration set is now created, but remains disabled until you switch it on.
- Before you switch on your configuration set, you can choose to enable Custom Locale Codes and Auto-Authorize
- 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.
- 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.
- 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".
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.
- Go to the GitHub Connector settings page. Stop the GitHub Connector, then add the language to the Smartling project.
- 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.
Mapping custom locale codes to a configuration
Yes, users can add custom mappings in Github Settings by doing the following;
- Temporarily disable the configuration set
- Click on the number after Custom Locale Codes
- Add desired custom mapping in the pop-up window
- Re-enable configuration set