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
- 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:
These are categories of commands. There are subcommands under each category.
Subcommands
Let's say we want to get some reports about my account:
We now see the available commands under reports
category. Let's use get-language-pairs-report
subcommand:
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:
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:
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):
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):
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:
If you have a more complex payload, we recommend putting it in a file first, and then piping the file into the command:
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
:
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:
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:
You can add a profile with this command:
Let's add a default profile:
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:
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
:
This rule tells motaword
CLI:
take all the files in my
src/en
directory 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.
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/strings
as the base directory for my source files. - Take
src/main/resources/translations
as the base directory for translated files. The last folder is different than the source path. - Translate all of
.json
files 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
.yml
files 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
.md
files 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/pot
directory 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-directory Given: ./source-directory/json-files/ui.json Then {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-directory Given: ./source-directory/json-files/ui.json Then {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-directory Given: ./source-directory/json-files/v1/public/ui.json Then {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:
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
This server cannot be installed
This MCP gives you full control over your translation projects from start to finish. You can log in anytime to see what stage your project is in — whether it’s being translated, reviewed, or completed.