Repository Connector Installation and Setup

Please note that this Connector is a paid product. For pricing information, please reach out to your Smartling Customer Success Manager.

Download the Repository Connector package and unpack it into the desired folder. 

Prerequisites 

• Installation must be done by a user who is familiar with command link, JSON, RegEx, and git.
• Adhere to all required parameters.
• The application should be hosted on a server that is continuously available.
• Java version 11 installed.
• Enough space to clone your Git repositories, as well as 50 MB for the installation of the Repository Connector.
• If GitHub or Smartling webhooks are to be used, the server needs to be publicly addressable.

Connect to Your Repository and Smartling

Configuration information for the Repository Connector is kept in two separate files. The first, repo-connector.conf, is part of the Repository Connector package and defines how the Repository Connector communicates with your repositories and with Smartling.

A second configuration file is placed in the repository, covering which files are uploaded to Smartling and the location of translated files in your repository. repo-connector.conf should be completed first. 

Repo-connector uses HOKON format for configuration. By default, the repo-connector.conf file is located in [repository connector directory]/cfg and defines the necessary parameters for the Repository Connector to access your repositories and listen for callbacks.

At a minimum, you must define a URL, access credentials, and a related Smartling Project for each of your repositories. Edits to repo-connector.conf must be valid JSON.

Environment Variables

Required Parameters

The package contains an annotated version of repo-connector.conf to help you set up the connector. The basic required parameters are as follows;

Repositories: Defines an array of source repositories. A repository cannot have more than one authentication attribute, and a public repository may have neither. Without authentication information, the connector will be able to get files from the repository but not download translated files from Smartling. Repositories have the following attributes:

• url: The URL for the repository. Must be unique in the array.
• alias: Alias for the repository. The alias is used in creating the file URI that is registered with Smartling for uploaded files. A unique alias value is recommended, but not required. The complete URI will be “alias/branch/file”, eg app1/translation/en_US.json
• type: Repository type. Possible values are GIT and SVN.
• smartlingProject: Defines your Smartling project credentials. You can find these in the Smartling Dashboard on the account-level API page. Note: This section was changed in version 1.5.0 and is not backwards compatible with previous versions.
  • projectId: Unique id for your project.
  • userIdentifier: The User Identifier for your Smartling v2 API Token.
  • tokenSecret: The token secret for your Smartling v2 API Token.
• resourcesConfig: The path to the repository configuration file, if hosted in your code repository. Default is ‘smartling-config.json’
• serverResourcesConfig: If you would prefer not to commit the repository configuration file to your code repository, you can host it on the Connector server. In this case, use serverResourcesConfig to define a path to the config file. You can define the absolute path or the relative path from the repo-connector.conf folder.
• namespace: TRUE or FALSE (default). If TRUE, strings are unique to each file. See the namespace documentation for more details. If FALSE, strings are shared between all files. Repeated strings are translated only once in Smartling. If your file names contain version information, this setting will avoid having to retranslate entire files when you upload a new version. Warning: This property should not be edited after you start uploading content to Smartling.
• branches: Regular expression for branch names to be checked for resources. If this is undefined, all branch names will be checked. (See JSON example below. The configuration will only monitor changes in branches that contain these words: dev, develop, dev_active-bookng, main, etc.)
  • "branches": "(dev\main)"
Remember that \ is an escape character both for JSON and RegEx, so you need to double-escape special characters for your Regular Expressions to work.
• pollingSchedule: Cron expression defining how often the Repository Connector polls your repository for updates. We strongly recommend using this method to upload new translatable files and download translations. However, if you need to upload new files to occur with minimum latency, you can set up a webhook.
• One of the following options should be used to define the authentication method and credentials the connector should use when connecting to the repository:
  • userPassword for username/password-based authentication. The username and password must be included in the configuration file or referenced via environment variables.
  • personalToken for personal access token-based authentication. The token must be included in the configuration file or referenced via an environment variable.
  • sshKey for ssh key-based authentication. The path to the key file along with the key pass phrase must be included in the configuration file or referenced via environment variables. NOTE: the key file must be of type RSA. To validate this, confirm that the key file starts with the line '-----BEGIN RSA PRIVATE KEY-----'. To generate keys of this type, use the command ssh-keygen -t rsa -m PEM
  • oauthToken for OAuth 2-based authentication. The client ID and client secret must be included in the configuration file or referenced via environment variables. In addition, for this authentication method, the connector needs to be able to open a browser window.
  • Scheduler. Defines a polling schedule for when the connector should check Smartling for completed translations.
  • checkTranslation: Cron expression defining how often the Connector will poll Smartling projects for updated translations. You must provide a valid expression, even if you set up webhooks and callbacks.

•  

Start the Repository Connector Application

To start the Repository Connector, execute:
java -jar repo-connector-1.5.5.jar -start

To stop the Repository Connector, execute:
java -jar repo-connector-1.5.5.jar -stop

If you have saved your configuration files in a folder other than the default (/cfg) add the parameter -configuration <folder_name> to the command.

To run as a daemon, execute:
java -jar repo-connector-1.5.5.jar -start&

Sending Content to Smartling

As part of configuring your repo connector, you will have defined a cron polling schedule that will check the repository for changes on a recurring basis and send any content changes to Smartling on the recurring basis defined. This is the simplest way to deal with sending new translations to Smartling and downloading translated files.

However, if it is vital to have new commits to your repository uploaded to Smartling with no latency, you can configure a webhook in your GitHub or Beanstalk repository. This will require additional technical resources and additional configuration to your Connector, outside Smartling.

Configuring Webhooks

Before you can get your webhooks working, you need to configure callbacks on your http listener settings in your repo-connector.conf file. It should look like this:

HTTP

"http": {
"host": "localhost",
"port": "5555",
"protocol": "http",
"callbackUrl": "http://callback.mydomain.com"
}

Parameters:

• host: The host name, set by default to localhost. Public server may require value to be set to 0.0.0.0
• port: The local port for the http listener. Any free port can be assigned.
• protocol: Can be set to http or https depending on the requirements of your server.
• callbackURL: URL for your instance of the Repository Connector. This is the URL that Smartling will send a callback to on completion of translation for a file.

Webhooks require your Connector to be publicly addressable. If you have set up the Connector behind a firewall, you may have difficulty getting your webhooks to work.

Currently, we support only GitHub and Beanstalk webhooks.

To configure a GitHub webhook, go to Settings > Webhooks for your repository and add a webhook. Required details are:

• Payload URL: Your publicly addressable URL for the connector. Takes the form https://{host}:{port}/github?resourcesConfig={path to config file}. Default resoucesConfig value is smartling-config.json. Your port value should match the one set in the http object in your repo-conenctor.conf file.
• Content type: Set to ‘application/json’.
• Secret: Your Smartling API token secret.
• Which events would you like to trigger this webhook?: Set ‘just the push event’.
  

For a Beanstalk repository, under Settings > Integration create a new webhook and set:

• Name: Choose a name for the webhook.
• URL: Your publicly addressable URL for the connector. takes the form

HTTP

http{/s}://{host}:{port}/beanstalkapp?userIdentifier={userIdentifier}&resourcesConfig={path to config file}.

Default resoucesConfig value is smartling-config.json. userIdentifier is your Smartlign API v2 user identifier. Your port value should match the one set in the http object in your repo-conenctor.conf file.

You do not need to make any changes to your repo-connector.conf file. If your webhook is set up correctly, any new push to the repository will trigger the connector to look for any changes to translatable files (or new files) to upload to Smartling.

Even if you set up callbacks, you must still provide a valid cron expression in the scheduler section of your repo-connector.conf.

Configure Your Translation Settings

Now that the Repository Connector is up and running, it’s time to set up how you will translate your project.