Twitch Intl CLI

A CLI utility for managing managing localized in typescript code, uploading and downloading from smartling (via Loom).

A primary feature is the ability to identify and extract strings from uses of formatMessage() function calls in typescript+react code, but flat string dictionaries in JSON format are also supported.

Background

This is a tool originally developed for the Twilight project. It is designed to work with the runtime package twitch-intl and handle the work of getting the strings in your Typescript code translated, and those translations back into your project. A core expectation is that your strings are tracked by your source control: either in code as function calls, or in a flat JSON file. If your strings exist in some other format, or simply don't live in source control, this isn't the tool for you.

This is published as an NPM package to the private Twitch NPM repository. Installing it locally to your project is recommended (yarn add --dev twitch-intl-cli) after which you may use it in your package.json scripts or via npx twitch-intl.

All sub-commands deal with "extracting" strings from your project, so you will be using one of either the --source-files or --strings-dict options to specify where your strings can be found.

All sub-commands besides extract require connectivity to Loom. The CLI will default to assuming AWS credentials with permissions to invoke Loom API endpoints are present in your environment. When running from a developer laptop, it is far easier to simply include the --midway flag to switch to Midway cookie-based authentication.

CLI Usage

The CLI is broken into several sub-commands, the primary two being upload and download.

Detailed help is available for each command in the shell.

Usage: twitch-intl [options] [command]

A simple CLI to manage localization. Uses `git` style subcommands.

Options:
  -V, --version               output the version number
  -h, --help                  display help for command

Commands:
  extract [options]           Extract messages found in formatMessage() calls.
  upload [options]            Upload extracted messages to Loom, optionally submitting them for translation
  download [options]          Download translated messages from smartling.
  submission-check [options]  Check for unsubmitted strings and fail if any are found
  help [command]              display help for command

twitch-intl upload

Usage: twitch-intl upload [options]

Upload extracted messages to Loom, optionally submitting them for translation

Options:
  -V, --version                  output the version number
  --exclude-from <remotebranch>  exclude strings committed in this git branch (e.g. "origin/main")
  --exclude-uploaded             exclude strings previously uploaded to Loom
  --jira-ticket <ticket>         produces a fatal error if not formatted like a JIRA ticket
  -P, --prompt                   display new/changed strings for confirmation before uploading, allowing for entry of
                                 context
  --submit                       submits strings for translation after uploading
  --force-submit                 (use with --submit) will overwrite all existing strings for given jira ticket
  --strings-dict <filePath>      Path to a flat JSON file of strings to use for the project
  -S, --source-files <fileGlob>  Glob matching TS files containing formatMessage calls
  --allow-top-level              Allow formatMessage to be called from a file-level context. (potentially before intl
                                 has initialized)
  --debug                        Enables debug output
  --format-func <func-name>      Set the name of the function used to translate strings (default: "formatMessage")
  -p, --project-id <id>          loom project id
  -m, --midway                   connect to Loom using Midway cookies over HTTPS instead of using local AWS credentials
                                 for direct lambda calls
  --loom-dev                     perform operations talking to loom-dev instead of loom-prod
  -h, --help                     display help for command

Typical usage of the upload command will probably look like:

twitch-intl upload --project-id moonlight --source-files "src/**/*.ts?(x)" --exclude-from origin/main --submit --prompt --jira-ticket LOC-9999

This will extract and submit any new/changed strings on disk for translation and comment on the corresponding Jira ticket.

twitch-intl download

Usage: twitch-intl download [options]

Download translated messages from Loom into a JSON file per locale

Options:
  -V, --version                  output the version number
  -o, --outfile <filename>       name of the output file to be created in each locale folder (default: "messages.json")
  -d, --outdir <path>            path to folder where language json folders will be saved (default: "./")
  --strings-dict <filePath>      Path to a flat JSON file of strings to use for the project
  -S, --source-files <fileGlob>  Glob matching TS files containing formatMessage calls
  --allow-top-level              Allow formatMessage to be called from a file-level context. (potentially before intl
                                 has initialized)
  --debug                        Enables debug output
  --format-func <func-name>      Set the name of the function used to translate strings (default: "formatMessage")
  -p, --project-id <id>          loom project id
  -m, --midway                   connect to i18n service using Midway authentication
  --loom-dev                     perform operations talking to loom-dev instead of loom-prod
  -h, --help                     display help for command

Typical useage of the download command will often look like:

twitch-intl download --project-id moonlight --source-files "src/**/*.ts?(x)" --outdir locales

This will extract the set of messages in use in the current codebase, then download and output JSON files into ./locales/<LOCALE>/messages.json for each enabled locale of the corresponding Smartling project.

twitch-intl submission-check

Usage: twitch-intl submission-check [options]

Check for unsubmitted strings and fail if any are found

Options:
  -V, --version                  output the version number
  -i, --invert                   Instead, fail when any strings found have been submitted (use with --format-func
                                 formatMessageDraft)
  --strings-dict <filePath>      Path to a flat JSON file of strings to use for the project
  -S, --source-files <fileGlob>  Glob matching TS files containing formatMessage calls
  --allow-top-level              Allow formatMessage to be called from a file-level context. (potentially before intl
                                 has initialized)
  --debug                        Enables debug output
  --format-func <func-name>      Set the name of the function used to translate strings (default: "formatMessage")
  -p, --project-id <id>          loom project id
  -m, --midway                   connect to i18n service using Midway authentication
  --loom-dev                     perform operations talking to loom-dev instead of loom-prod
  -h, --help                     display help for command

Example:

twitch-intl submission-check --project-id moonlight --source-files "src/**/*.ts?(x)"

This exits with a non-zero status code if any strings found in the current codebase are unknown to Loom. This is most useful for a CI check to prevent merges with untranslated strings.

Developing

yarn start will spin up a local dev server for working on the web UI for string confirmation. yarn build compiles the code into a shipable dist folder. yarn test runs all the tests!

Releasing

1. Update src/config.ts with the new version, commit to git.
2. Run yarn version to set the new version to match. (creates git commit and tags)
3. Push with tags git push --follow-tags and publish npm publish