Setting up your GitHub Connector
This article is for Account Owners and Project Managers user in Smartling and Admin users in GitHub.
This article will walk you through the following steps to set up your Smartling GitHub Connector:
- Setting up your Admin Team in GitHub
- Connecting GitHub to Smartling
- Configuring the 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
- 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.
- 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.
Connecting GitHub to 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
- 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, Authorize the Smartling GitHub Connector.
- 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 connector will be able to access the organization, and the user will be able to see the organization on the Github Settings page.
- Once authorized, your Smartling user email will match the GitHub user email and associated Organizations in GitHub. Select the GitHub Organization name, Repository name and Branch name
- Click Next
- 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 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/