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/en directory as source files and put their translations in the same path structure inside the src/{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/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 in src/main/resources/strings/frontend/json/ directory, without going down subdirectories
1. And put their (e.g. French) translations into src/main/resources/translations/fr/frontend/json/
Translate all of .yml files under src/main/resources/strings/frontend/ directory, going recursively in all subdirectories
1. And put their (e.g. French) translations under src/main/resources/translations/fr/, by using respective relative path of the source file.
Translate all of .md files in src/main/resources/strings/md/ directory, without going down subdirectories
1. And put their (e.g. French) translations into src/main/resources/translations/fr/md/
And finally, while doing all of that, exclude all files in src/main/resources/strings/pot directory whose file name starts with passwords.

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.