Smartestling

A smarter-er nodejs utility for automating tasks with the Smartling v2.0.0 REST API.

🎬 Getting Started

Globally install this npm package usning Yarn:

yarn global add @blockfolio/smartestling

Alternatively, you can locally install within another project and run via that project's npm scripts:

# install as a devDependency
yarn add --dev @blockfolio/smartestling

// put the 'smartestling' command within 'scripts' so the project's local version is used
{
  "scripts": {
    "translate": "smartestling"
  }
}

🇺🇳 Translating Files

Run the smartestling command to translate files according to the smartestling config file.

> smartestling --help
Usage: smartestling [options]

Options:
  -V, --version                output the version number
  -c, --config [CONFIG_FILE]   use a non-standard config filename (default: "smartestling.yml")
  -u, --upload                 upload files only
  -d, --download               download files only
  -x, --use-cache              whether or not to use cache
  -a, --cache-dir <CACHE_DIR>  cache directory for downloaded file
  -h, --help                   output usage information

🗺 Commands

• The -c argument defines a configuration file to use, this value defaults to smartestling.yml
• The -u argument tells smartestling to upload files
• The -d argument tells smartestling to download files
• The -x argument tells smartestling to use cache for translations, avoiding contacting smartestling for them. This must be used in conjunction with the -a argument
• The -a argument tells smartestling where to cache translations. This can be used with or without the -x argument. When used without the -x argument, smartestling will always download the translations but still write them to cache, and fallback to the cache if the download fails. When used with the -x argument smartestling will never download the translations, it will only use them from the cache.
• If neither upload or download is specified, smartestling will both upload and download.
• Smartestling always uploads before downloading.

⚙️ Configuration Settings

The configuration file is broken into two sections: Global configuration (config:), and Per file (files:):

# Example of a smartestling config file:

config:
  project-id: 'SMARTLING_PROJECT_ID'
  token-secret: 'SMARTLING_API_TOKEN_SECRET'
  user-identifier: 'SMARTLING_API_USER_IDENTIFIER'

files:
  'App/services/i18n/translations/en.json': # required, path to this translation source file
    save-pattern: 'App/services/i18n/translations/{language}.json'
    file-type: 'json' # required, type of file
    approve-content: true # optional, default: false
    retrieval-type: 'published' # optional, default: 'published'

🌎 Global

The global configuration has settings for connecting to the Smartling API and selecting the appropriate project:

• project-id (required) the project-id as specified by the Smartling Dashboard
• token-secret (required) the token-secret provided by Smartling
• user-identifier (required) the user-identifier provided by Smartling that corresponds to the token-secret

🏙 Per-file

The files section contains configuration about each file that you want translated. Each file falls beneath the files: top level configuration and has the following options:

• save-pattern (required) the pattern to use for saving the translated files
  • token: {locale} can be used to place the locale into the path, it is in the format: en-US
  • token: {locale_underscore} can be used to place the locale into the path, it is in the format: en_US
  • token: {language} can be used to place the language into the path, it is in the format: en
  • token: {region} can be used to place the region into the path, it is in the format: US
• file-type (required) the file type, this must be one of the values supported by Smartling
• approve-content (optional, default: true) whether or not to automatically approve uploaded content
• retrieval-type (optional, default: published) the type of files to download

🗽 Contributing

Want to help us improve this utility? Fork this repository and submit a pull request! We only ask that everyone abides by the Contributor Covenant Code of Conduct.

IMPORTANT! All commits must adhere to the semantic-release naming convention, in order to properly calculate the npm version increment and auto-publish to the npm registry.

☑️ Todo

The following items are a good starting point for a pull request:

• Test coverage (none right now, but ideally test with multiple source / retrieval file types)
• Retry after cooldown upon receiving 429 rate exceeded response
• Refresh accessToken after expiration
• Support more parameters via configuration file, as defined in the Smartling API

⚖️ Legal

Released under the MIT license.