Repository Connector

Repository Connector Installation and Setup

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

As of version 1.5.0, the Repository Connector uses version 2 of the Smartling File API. This version is not backwards compatible with previous versions and requires new API credentials. See Authentication or help obtaining the User Identifier and User Secret you will need to set up the connector.

Prerequisites 

  • The application should be hosted on a server that is continuously available and/or publicly addressable.
  • Java version 8 or higher.
  • Disk space requirements: It should have enough space to clone your Git repositories, as well as 50MB for the installation of the Repository Connector.

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 where translated files end up in your repository. repo-connector.conf should be completed first.

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.

The repo-connector.conf file also supports the use of environment variables. You can use them as a value to any of the file's parameters by adding them in the format; ${ENVIRONMENT_VARIABLE_NAME}.

For additional configuration see the Advanced Configuration instructions.

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.
  • userPassword (optional): Defines user/password authentication type for a Github repository. Other authentication options are available.
    • user: User name
    • password: User password
  • 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.
  • resourcesConfigr: 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 the upload new files to occur with minimum latency, you can set up a webhook.
  • Scheduler
    • 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.
    • Other authentication options are included in the example file.

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 of 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.

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’.
    webhooks.png

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.

Was this article helpful?