motaword CLI
Use MotaWord CLI to interact with your MotaWord account in many ways to manage your translation and localization needs.
Explore the docs »
Request Feature
·
Report Bug
Table of Contents
About motaword
Use MotaWord CLI to interact with your MotaWord account in many ways to manage your translation and localization needs.
You can use motaword locally or as part of your CI/CD for continuous localization of your software.
Getting Started
To get a local copy up and running follow these simple steps.
Download pre-built binary
Use Releases in this GitHub repository and download the application for your respective platform. We release motaword for Linux, Windows and MacOS in various configurations.
Download here: Releases
Install via bash installer
We provide an installer.sh bash script that you use with curl to install the latest version of motaword CLI in your working directory. You can find the installer.sh script in this repository.
You can install motaword by running this:
curl -s https://raw.githubusercontent.com/motaword/cli/master/installer.sh | bash
Install via Homebrew
Mac users can install motaword simply via homebrew:
- Tap us
brew tap motaword/homebrew-tap - Install
motawordbrew install motaword
Now you can run motaword anywhere in your system.
Usage
Command categories / parent commands
motaword allows you to access all aspects of MotaWord platform, from submitting files for translation to getting reports, from managing your glossary to style guides.
For all commands that motaword support, run:
> motaword help
Usage:
motaword [command]
Available Commands:
async Manage async operations
auth Authentication settings
continuous-projects Manage your continuous projects
debug Debug your MotaWord configuration and environment
documents Manage documents
get-access-token Retrieve an access token to interact with the API.
glossaries Manage glossaries
help Help about any command
help-config Show CLI configuration help
help-input Show CLI input help
projects Manage projects
reports Manage reports
search Manage search operations
static Manage static endpoints
stats Manage stats
strings Manage strings
styleguides Manage styleguides
translate Instantly translate your content with your existing TM and MT resources. This is an alias to `continuous-projects translate`
users Manage users
webhooks Manage webhooks
Flags:
-h, --help help for motaword
-o, --output-format string Output format [json, yaml] (default "json")
--profile string Credentials profile to use for authentication (default "default")
-q, --query string Filter / project results using JMESPath
--raw Output result as raw rather than pretty JSON
--server string Override server URL
--v Enable WARN level verbose log output
--verbose Enable DEBUG level verbose log output, same as --vvv flag
--vv Enable INFO level verbose log output
--vvv Enable DEBUG level verbose log output
Additional help topics:
motaword blog Manage blog articles
motaword clients Manage client account
motaword token Manage token operations
Use "motaword [command] --help" for more information about a command.
These are categories of commands. There are subcommands under each category.
Subcommands
Let's say we want to get some reports about my account:
> motaword reports
Usage:
motaword reports [command]
Available Commands:
get-language-pairs-report Returns a report of language pairs.
get-projects-report Returns a report of corporate account users.
get-users-report Returns a report of corporate account users.
We now see the available commands under reports category. Let's use get-language-pairs-report subcommand:
> motaword reports get-language-pairs-report
{
"meta": {
"paging": {
"links": {
"next": null,
"previous": null,
"self": {
"href": "https://api.staging.motaword.com/v0/reports/language-pairs"
}
},
"page": 1,
"per_page": 2,
"total_count": 2
}
},
"report": [
{
"language_pair": {
"source_language": "af",
"target_language": "ak"
},
"spending": "343.42",
"word_count": "2475"
},
{
"language_pair": {
"source_language": "en-US",
"target_language": "fr"
},
"spending": "11.70",
"word_count": "195"
}
]
}
Most commands will return a JSON response. By using a tool like jq, you can process these JSON responses. Here is an example for getting a human-readable output from the above response:
> motaword reports get-language-pairs-report \
| jq '.report[] | "For \(.language_pair.source_language) into \(.language_pair.target_language), we spent $\(.spending)"'
"For af into ak, we spent $343.42"
"For en-US into fr, we spent $11.70"
Command parameters
Some commands accept parameters and JSON payloads. We can view what kind of parameters or JSON payload they can accept, we can use the --help flag:
> motaword projects get-project --help
Get single project
Usage:
motaword projects get-project id [flags]
Flags:
-h, --help help for get-project
--with[] string Include detailed information. Possible values 'client', 'vendor', 'score'
get-project command only accepts and id parameter and with[] flag.
Some commands will accept JSON payloads, these are usually create/update commands (e.g. POST/PUT requests in HTTP).
We can view the shape of the request payload via --help. The request description is an OpenAPI specification. Here is an example (removed descriptions for brevity):
> motaword reports get-projects-report --help
## Request Schema (application/json)
properties:
budget_code:
type: string
date_from:
format: date-time
type: string
date_to:
format: date-time
type: string
source_languages:
items:
type: string
type: array
target_languages:
items:
type: string
type: array
users:
items:
format: int64
type: integer
type: array
type: object
Usage:
motaword reports get-projects-report [flags]
Flags:
-h, --help help for get-projects-report
According to the request schema in the help output, you can send this payload with this command (which will generate your projects report within these dates):
{
"date_from":"2021-04-21T16:07:12.727Z",
"date_to":"2021-05-21T16:07:12.727Z"
}
Sending JSON payload
JSON payloads like above can be sent by piping STDIN into the command.
If you have a simple payload, you can simply do this:
> echo '{"date_from":"2021-05-21T16:07:12.727Z","date_to":"2021-05-21T16:07:12.727Z"}' \
| motaword reports get-projects-report
If you have a more complex payload, we recommend putting it in a file first, and then piping the file into the command:
> motaword reports get-projects-report < my-complex-payload.json
Configuration
motaword CLI application looks for .motaword/ directory to configure itself. It looks for configuration in this order:
- Working directory
$HOME/.motaword/etc/.motaword
We keep 2 files in this directory:
- credentials.json
- config.json
credentials.json holds your MotaWord API client ID and client secret. This file can be generated via motaword CLI itself. See Authentication below for more information.
config.json lets you configure all aspects of your motaword CLI, and especially tailored for motaword translate command which is typically used in development and CI/CD environments. You can learn more about translate command below.
Unless you are using translate command, config.json file is optional.
Authenticating
TL;DR
Add a default authentication profile to automatically create .motaword/credentials.json:
motaword auth add-profile client-credentials default MY-CLIENT-ID MY-CLIENT-SECRET
Authentication details
motaword CLI requires a MotaWord developer account and an API client ("app" as we call them). You can create one here: https://www.motaword.com/developer
Once you have a developer account, create a new app on your Developer Portal. Now you can access your API client ID and secret for this app.
You need to use these keys with your motaword CLI by putting them in .motaword/credentials.json file. This is what credentials.json looks like:
{
"profiles": {
"default": {
"client_id": "my-client-id",
"client_secret": "my-client-secret",
"type": "client-credentials"
}
}
}
motaword CLI lets you have multiple profiles for authentication. default profile is sufficient in most use cases, but you can have multiple profiles with arbitrary names (e.g secondary-profile in place of default in the example above).
We provide a way to automatically manage your authentication profiles:
> motaword auth
Authentication settings
Usage:
motaword auth [command]
Available Commands:
add-profile Add user profile for authentication
list-profiles List available configured authentication profiles
Flags:
-h, --help help for auth
You can add a profile with this command:
> motaword auth add-profile client-credentials <name> <client-id> <client-secret>
Let's add a default profile:
motaword auth add-profile client-credentials default my-client-id my-client-secret
That's it! motaword CLI will manage the authentication for you including reusing and refreshing your API access tokens.
Translating
Needless to say, translating your files is the most important thing that our CLI tool does. You can use any of the document upload, project download/package commands, BUT, there is one exclusive command that solves everything for you:
> motaword translate --help
Usage:
motaword translate [target-language] [flags]
Flags:
-h, --help help for translate
This command is much smarter than it looks and comes with its own set of configuration to handle your file translations. This is especially used in code bases and CI/CD environments.
What does it do exactly? It uploads your language resource files, downloads the translated versions and puts them in the correct place in your directory structure. Let's dive in.
Configuring translations
translate command comes with a highly flexible configuration to enable your translations in all use cases. Let's take a look at them:
| Config Key | Type | Required | Default Value | Description |
|---|---|---|---|---|
| project-id | integer | string | yes | null | This is the continuous project ID given to you by MotaWord. |
| source-directory | string | yes | null | The base directory for motaword CLI to start looking for source files. The actual source file detection can be managed by rules configuration. All rules are based on this source directory. |
| translations-directory | string | no | source-directory/{locale} | The base directory for motaword CLI to start placing your translated files. The translated file patterns rules configuration will be based on this directory. Can be same with source-directory. By default, we will put translations in each {locale} directory under source-directory. Beware, the default value is probably not the correct way in your case. |
| rules | JSON Map {string: string} | yes | { "**/*" : "{path}/{basename}" } | List of glob-like file path patterns to specify your source files and how to place their translated versions. See below for more available variables, detailed explanation and examples. |
| exclude-rules | JSON Array [string] | no | [] | List of glob-like excluded source file patterns. We will skip these files during translation. |
Translation rules
rules configuration is quite versatile to enable the correct directory structure in many use cases. Each rule uses glob-like path patterns to collect a list of source files. You can specify multiple rules to combine different directory structures into your MotaWord translations.
Let's look at the default value for rules:
{
"source-directory": "src/en",
"translations-directory": "src/{locale}",
"rules": {
"**/*": "{path}/{basename}"
}
}
This rule tells motaword CLI:
take all the files in my
src/endirectory as source files and put their translations in the same path structure inside thesrc/{locale}directory where{locale}is each of your translation languages.
If your source and translations directories are organized in a simple manner, this can be sufficient for you. However, rules can handle very complex use cases. Let's take a look at one that is a little more complex than the default one:
You should look at the section Available variables in rules before the complex example, it will make the example easier to digest.
{
"source-directory": "src/main/resources/strings",
"translations-directory": "src/main/resources/translations",
"rules": {
"frontend/json/*.json": "{locale}/{path}/{basename}",
"frontend/**/*.yml": "{locale}/{path}/{filename}.yaml",
"pot/*.pot": "{locale}/{path}/{basename}",
"md/*.md": "markdown-translations/{locale}/{path}/{filename}.md"
},
"exclude-rules": [
"pot/passwords*"
]
}
A rules configuration like this says a lot :)
To debug and understand what your rules say, you can always run motaword debug. It will tell you how your rules are interpreted.
Let's go through the complex rules above:
Given we are translating our files into French, which has the language code
fr
- Take
src/main/resources/stringsas the base directory for my source files. - Take
src/main/resources/translationsas the base directory for translated files. The last folder is different than the source path. - Translate all of
.jsonfiles insrc/main/resources/strings/frontend/json/directory, without going down subdirectories- And put their (e.g. French) translations into
src/main/resources/translations/fr/frontend/json/
- And put their (e.g. French) translations into
- Translate all of
.ymlfiles undersrc/main/resources/strings/frontend/directory, going recursively in all subdirectories- And put their (e.g. French) translations under
src/main/resources/translations/fr/, by using respective relative path of the source file.
- And put their (e.g. French) translations under
- Translate all of
.mdfiles insrc/main/resources/strings/md/directory, without going down subdirectories- And put their (e.g. French) translations into
src/main/resources/translations/fr/md/
- And put their (e.g. French) translations into
- And finally, while doing all of that, exclude all files in
src/main/resources/strings/potdirectory whose file name starts withpasswords.
If you are still here, you are an expert motaword configurer :)
Available variables in rules
| Variable | Description | Example |
|---|---|---|
{basename} | Full name of the file, including file extension | If source directory is: ./source-directoryGiven: ./source-directory/json-files/ui.jsonThen {basename}: ui.json |
{filename} | Name of the file without the file extension. This variable is usually used to change the extension of translated files. | If source directory is: ./source-directoryGiven: ./source-directory/json-files/ui.jsonThen {filename}: ui |
{path} | The directory path from the source directory onto the file. This is the most useful variable to modify your directory structure. | If source directory is: ./source-directoryGiven: ./source-directory/json-files/v1/public/ui.jsonThen {path}: json-files/v1/public |
{locale} | The translation language code that is being processed. This is most useful when your translation directories have different needs for target language directories. | en-US, fr, zh-CN etc... |
Translation configuration examples
Look at the ./examples directory in this repository for various configuration examples.
Debugging
All motaword CLI commands can get some debugging flags. Use --help to see the flags.
You can configure the level of output by using verbose flags:
| Flag | |
|---|---|
--v | WARN level logs |
--vv | INFO level logs |
--vvv or --verbose | DEBUG level logs |
There is also a debug command available for your config.json configuration file:
> motaword debug
This will output the detected source files and their corresponding translation paths.
Contact
24/7 FREE technical or business live chat support: https://www.motaword.com