GitHub Connector FAQs
Why does Smartling require the user to be an Admin instead of just Read/Write access? And can I change the user's permissions after the installation?
A Smartling user needs to be an Admin because we require the "Change a repository's settings" permission in order to add and remove our webhooks. Starting and stopping the connector in Smartling will install and uninstall the webhooks, therefore, changing permissions after the connector is installed will result in errors and unexpected behavior from the connector. Users should keep their Admin level permissions.
Each time you add a new Admin to your Github, you will need to create a new configuration set in Smartling for that user's repo.
When setting up the connector, which branch should I select?
For most users, the main (master) branch can be used. However, to avoid any localization issues corrupting the main (master) branch, it is worth considering creating another branch, such as a dev branch, for translations to be returned from Smartling to before the main (master) branch. If you already have a process where localization happens in a different long-lived branch, you can select that branch instead.
How do I add 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 connector settings page. Stop the connector, then add the language to the Smartling project.
- Start the connector.
Result: The 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 connector will continue to operate as normal, picking up any new pull requests, and creating new jobs for all languages.
- Option 2: Add a language and wait for the next pull request 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 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. This means that it can take time to pick up all the files.
Note: If at any time the 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.
Can I map custom locale codes to my 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
Why are some strings being duplicated in Smartling?
Smartling will generally avoid repetitions and duplications especially when a file is simply being updated/revised. In some cases, repetitions or duplicates are created by design. For example, if a string exists with a different key, or in a different file, it is captured as a separate, unique string. This is important because when used in a different context, the translation might be different. For more detail on how this works, see string uniqueness and SmartMatch, as well as how to optimize the translation process when you have repetitions.
Do I have to wait for all translations to be completed?
As a best practice, we recommend that your resource files get fully translated in all of your project’s languages. However, if you need to unblock the original pull request or just get the latest translations, there are a few options that all have different pros and cons.
- Option 1: Keep the translation process going (keep the pull request blocked), including the dependent branches, active, but get the latest translations to use. Using either the Smartling Dashboard or APIs (via the CLI tool or other methods), download the translated files for the languages you want (optionally downloading pending translations for any language) and then deploy them as needed.
- Option 2: Unblock the pull request by merging just the languages that are completed. Using the Smartling Dashboard UI, update the job for the corresponding branch by removing the languages that you do not want to wait for. When all languages that remain in the job are completed, the job will automatically update to be "Completed", and trigger the standard flow for the connector. In this case, only the languages remaining in the job will be in the resulting pull request. Note: Removing the language from the job will unauthorize the translations of the strings that are not yet published, losing any translation work that has already been done.
- Option 3: Unblock the pull request completely, without any translations merged.
- Option 4: Depending on your GitHub configuration, you can disregard the flag and proceed with the merge, or if it is configured to block pull requests from the merge, it can be overridden by an admin.
- Option 5: Completely cancel the job in Smartling.
Can I connect to a self hosted GitHub instance (GitHub Enterprise)?
No. For options, consult the consult the Options for Automation With Source Repositories article.
Can I change the branch that the connector monitors for pull requests?
No. If you'd like to configure the connector to monitor a different branch, you'll need to create a new Smartling GitHub connector project. During the project wizard, you can choose the repository and branch.
If you want to change the branch, and need help migrating from one project to a new one, contact email@example.com.
Why are translations not being delivered using the translation path that is in my current configuration?
The configuration information present at the moment a file is uploaded to Smartling from a PR is persisted with that version of the file and used for its delivery. Changes to the configuration will be in effect only for new PRs and files uploaded after the configurations is saved.