When working with localized content in an agile, continuous deployment environment, it is critical to optimize for translation speed. The Repository Connector is designed to shorten the time it takes to translate new content by automatically pushing changes to resource files in a GitHub, GitLab, or Beanstalk repository to the Smartling dashboard and pushing new translations back to the repository.
The Repository Connector acts as a broker between the source repository ran on your server and the Smartling project. Changes to resource files in the repository are automatically pushed to the Smartling project. The Connector will register a callback for each file so that it can be notified when the file is completely translated, then it will immediately download the translated file and can optionally push the translated files back to the repository.
The Repository Connector;
- Monitors your resource files sets for any changes and sends any updates to Smartling for translation on a polling schedule.
- Based on your configuration, when changes are committed and the content is sent to Smartling, the translations process will either initiate automatically or manually.
- Once all authorized strings are published for locale, it will send the translations back to the repository and the file is updated automatically, on another polling schedule.
- Note, this means that the translated file is returned even if some strings remain awaiting authorization
- Read our FAQ for options on downloading translated files
Options for Translation
Depending on your resources and if you're translating into all languages configured or just a subset of languages, here are some considerations for your translations process;
Auto-authorize
Configuration: authorizeContent = true / false
By default, auto-authorize is defined as true in the repo configuration. This means that any updates committed in the repository will be sent to Smartling on a polling schedule and the content will be batched together in a "DailyUploads" job and automatically authorized for translation. This automated option requires fewer resources in your translation process and can save time in ensuring translations are initiated and completed automatically.
If 'false', any updates committed in the repository will still be sent to Smartling on a polling schedule, but the content will not be batched together in a job and will remain in the Awaiting Authorization queue until a user manually authorizes the translation. This manual option is recommended if you want to separate the content into various jobs. The user has the option to create a new job each time or add the content to an existing job. The user can then easily monitor and manage the translation of the content in Smartling on a job-specific level, rather than managing translations in one 'bucket' job.
Manual-authorization with Jobs Automation Rules
The volume of changes committed and the frequency of the polling schedule will define how much content is batch into one "DailyUploads" job. Considering that translations are only returned when the locale is completely translated (published), it might be worth considering relying on supporting tools to batch content into smaller jobs to assist in returning translations quicker. You can choose to have content sent to Smartling but be automatically batched into a job and authorized for translation by setting Job Automation rules. Jobs Automation rules are configured in Smartling and work alongside the repo configuration.
Webhooks
As mentioned, all of the above configurations will send content to Smartling for translation on a polling schedule defined in your repo configuration. If it is vital to have new commits to your repository sent to Smartling with no latency, you can configure a webhook in your GitHub or Beanstalk repository.
The webhook configuration works together with the polling schedule configuration to ensure all content is sent to Smartling as soon as it is committed, and the repo is continuously checked for commits on a recurring basis. How the content is batched and authorized is decided from the above options.
This will require additional technical resources to configure the webhook on your Connector. The webhook also requires your Connector to be publicly addressable, which may be problematic if you have set up the Connector behind a firewall.
See the Configuring Webhooks section of Repository Connector Installation and Setup documentation for how to configure a webhook.
Recommended Configurations
Translating content into all languages
- Auto authorize = true
- Auto authorize = false, with Jobs Automation rules to create a job for all languages.
Translating content into a subset of languages
- Auto-authorize = true, with the subset of locales defined in the resource set of the repository configuration.
Translating content updates as quickly as possible
- Auto authorize = true
- Webhooks configured
Configuration Expected Behavior
Schedule |
Auto-Authorize |
Jobs Automation |
Result |
Polling |
True |
N |
Default configuration.
Repo is checked for commits based on the schedule.
Recommended for most use-cases. |
Polling |
False |
N |
Repo is checked for commits based on the schedule.
The content will be sent to Smartling only. Manual Authorization required.
Recommended if you have an internal Smartling user and want to manage translations in a more granular method. |
Polling |
False |
Y |
Repo is checked for commits based on the schedule.
The content will be sent to Smartling and, based on the Jobs Automation Rules applied, batched into Job, and automatically authorized.
Recommended for translation into all languages in the Smartling project. |
Polling + Webhook |
True |
N |
Content updates are sent to Smartling as soon as they are committed. Repo is also checked for commits based on the schedule as a backup.
The content will be sent to Smartling and batched into a DailyJobs ‘bucket’ job, and automatically authorized.
Recommended for most use-cases, if you have internal technical resources available. |
Polling + Webhook |
False |
N |
Content updates are sent to Smartling as soon as they are committed. Repo is also checked for commits based on the schedule as a backup.
The content will be sent to Smartling only. Manual Authorization required.
Recommended if you have internal technical resources available, as well as an internal Smartling user, and want to manage translations in a more granular method. |
Polling + Webhook |
False |
Y |
Content updates are sent to Smartling as soon as they are committed. Repo is also checked for commits based on the schedule as a backup.
The content will be sent to Smartling and, based on the Jobs Automation Rules applied, batched into Job, and automatically authorized.
Recommended if you have internal technical resources available, and for translation into all languages in the Smartling project. |
When to Use the Repository Connector
While the Repository Connector gives you many options for configuration, it is primarily intended as a ‘one-size-fits-most’ convenience method for handling simple integrations without needing to create a custom integration, using Smartling API. If the codebase in your project is kept in a single code repository, and you have simple conventions for storing and accessing your translated resource files, the repository connector is likely to be the simplest solution.
If your project is complex, exists across multiple repositories, or requires different handling for different locales, it may be easier to use the Smartling API to create a custom integration from scratch. Our SDKs give you powerful tools to quickly develop the ideal integration process for your app. This is especially true if you need to run checks or tests on translations.
For example, the repository connector will automatically pick up any changes to your source files and deliver translations of authorized strings when they are complete. For unique circumstances, consider a custom integration designed for the unique needs of your app.
Before working with the Repository Connector, review the article describing multiple options for integrating Smartling with your code repository.