Setup & Configuration
Can I connect to a self-hosted GitHub instance, i.e. GitHub Enterprise?
No. However, if your GitHub Enterprise is hosted on github.com, this is compatible with the GitHub Connector. For alternative options, consult our documentation on Options for Automation With Source Repositories.
Which authentication type should I use (OAuth App or GitHub App)?
We recommend using the GitHub App. The GitHub App is generally preferred over the OAuth model, as it provides a more modern, secure, and scalable way of connecting your Smartling account to GitHub. For more information see Types of Authentication for the GitHub Connector.
When authenticating with OAuth App, why does Smartling require the user to be a Repo Admin instead of just Read/Write access?
When authenticating with OAuth App, a Smartling user needs to be an Admin on the repository and a member of the GitHub Organization. This is because we require the "Change a repository's settings" permissions to add and remove our webhooks. Starting and stopping the GitHub Connector in Smartling will install and uninstall the webhooks, therefore, changing permissions after the GitHub Connector is installed will result in errors and unexpected behavior from the GitHub Connector.
Each time you add a new member to your GitHub, you will need to create a new configuration set in Smartling for that user's repo. Furthermore, any configuration set created uses OAuth and therefore the account you are logged into in GitHub is the user account the connector uses to authenticate the configuration set. For this reason, we recommend creating a dedicated Admin user for the GitHub Connector.
If your developer creates configuration sets, they must be logged into GitHub as a member and Admin in the Repo. Overlooking this may result in multiple configuration sets relying on the permissions from multiple different accounts from the various people who created them.
Tip: For more information, read our documentation on Setting Up the GitHub Connector with OAuth App.
Can I change the authentication user on the connector?
Yes. For more information, read Changing Authentication Users on The GitHub Connector.
Can I change my existing configuration sets from using OAuth App to using the GitHub app?
Yes. For more information, read Migrating from OAuth App to GitHub App.
When setting up the GitHub Connector, which configuration mode should I select?
It really depends on your organization's needs, its development process and its localization process. For more information, read our documentation on GitHub Configuration Modes.
When setting up the GitHub 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. For more information, read our documentation on GitHub Branch Strategy.
Does the GitHub Connector always monitor pull requests/commits in the repository of the configuration set?
Yes. The connector has to monitor every pull request/commit in the repository of the configuration set. It ignores any pull request/commit outside what is specified in the configuration set. For more information, read our documentation on Configuration Sets.
Can I customize the configuration set, like mapping custom locale codes or automatically authorize Jobs?
Yes. For more information, read our documentation on Customizing Configuration Sets.
Content
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 intentionally. 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.
For more information, read our documentation on Strings.
Why is some previously translated content awaiting authorization?
Files from different repositories or branches are treated as different files in Smartling, and therefore, recognized as new content for translation.
Tip: Use SmartMatch rules to leverage preexisting translations, reduce translation costs and speed up delivery.
How do I add a new language?
For options on how to add a new language to the GitHub Connector, read Adding a new language to the GitHub Connector.
Jobs
Is there a way to prevent Job creation from pull requests until the content has been finalized?
Yes. You can set a Translation Hold label on the configuration sets on Pull Request mode. For more information, read our documentation on the Translation Hold setting.
Why is my Job empty or canceled?
An empty or canceled Job with "no content" occurs when there is no new content to translate in the source file that triggered the Job. When receiving the file from GitHub, the Connector does not yet know if there is new content for translation, but it must create a Job as a container for that file. After the file is parsed, the Connector will cancel the Job if no new text requires a translation. If this is a recurring issue, consider changing the branch the connector is watching or using a different mode on your configuration set so that changes are only picked up when they are committed or manually pushed to Smartling.
Job cancellation can also occur when structural changes are made to the source file(s) that don't require translation. In those cases, the connector must sync up the structure of the translated files to match the source.
Examples of structural changes include:
- Removing strings from a source file
- Adding/modifying non-translation elements like comments
- Re-ordering strings within a file
Tip: For more information on empty Jobs, read our documentation on Troubleshooting No Content.
Why is some source content not in the Job/removed from the Job?
The likely cause for content not being in the Job or being removed from the Job is that the source file has been updated and pushed to Smartling. If your configuration set job options is set to reuse an existing Job, this overwrites the source content with any changes made. If you push content to Smartling at a high frequency, or often update source files, we recommend setting the configuration set to always create a new Job.
Tip: For more information on content being removed from a Job, read our documentation on Troubleshooting Content Being Removed From a Job.
Translation Delivery
Why does the translated file contain some untranslated content?
This likely means the content in the file is in translation in another Job, and the content is not yet published in that other Job.
Strings are translated based on file URI, which includes configuration set ID + branch name + folder + filename and extension, collectively. If any of the file URI elements vary, the string is treated as unique in SMartling and could return to your translation pull request untranslated (because it is translated elsewhere).
In your GitHub project in Smartling, click the GitHub tab to search for the file with untranslated content, ensuring you select the one that corresponds to the right repository/branch you submitted from. Click on the file tile to check the progress and confirm if any of its contents are not published.
Tip: For more information, read our documentation on Troubleshooting Untranslated Content.
Can I merge the original source pull request before translations are complete? (PR Mode)
The original pull request must remain open until the Job is complete so that translations can be delivered. Merging earlier than this will prevent translations from being delivered. If your development process means that you must merge the pull request as soon as possible, you should set the configuration set to Single Branch Mode.
Tip: For more information, read our documentation on GitHub Configuration Modes.
Why does the translated file contain strings that were not in the original source file?
This is because for a given organization configuration set + repository + branch + filename combination, Smartling retains only the latest version of the file.
Smartling can then add new content from the file to Jobs as needed. If you delete content from the file, those strings are removed from the Job and are marked as inactive in Smartling.
If several developers push the same file through successive pull requests or commits containing content additions/removals, Smartling will only keep the latest version and only translate that content in the relevant Jobs. This ensures that the file delivered back is the latest one with the latest translations at all times.
Why are translations being delivered using a different translation path than is in my current configuration?
The configuration information present the moment a file is uploaded to Smartling from a pull request or commit is persisted with that version of the file and used for its delivery. Changes to the configuration will be in effect only for new pull requests or commits and files uploaded after the configurations is saved. For more information, read the GitHub Connector Overview.
Why was nothing delivered to GitHub when I tried to manually export translations from Smartling?
To deliver translations, Smartling creates a branch called "smartling-translations-completed-[Job ID]-[date+time]". It commits the files to that branch and opens a pull request to the watched branch from the configuration set.
GitHub only lets you create a PR if you are making a change to a file relative to what is already committed in the target branch. If you are pushing translations to a branch, but those translations are already part of that branch, then there is nothing to do, and the PR is not created. Changes in PRs which are open (i.e. not merged) don’t count as part of the branch, and there isn’t a restriction on another PR making the same changes to the same files.
If nothing was delivered, check your branches for any "smartling-translations" branch that may already contain the latest files. Additionally, check that there is actually the change you expect in the localized files from Smartling when compared to the latest localized files in your repository.
How can I edit translations and have them delivered back to GitHub?
You will need to push the strings back in the workflow or use manual export. For more information, read Updating Translations with the GitHub Connector.
Are prepublished translations delivered back to GitHub?
Not by default. Because translation delivery relies on Job completion, prepublishing does not send current translations to GitHub. However, you can get prepublished translations delivered early on Pull Request Mode and Single Branch Mode by enabling Early Delivery.