Command-line tools to lint, extract, and inline format-message translations

API

All of the command line tools will look for requireing or importing format-message in your source files to determine the local name of the formatMessage function. Then they will either check for problems, extract the original message patterns, or replace the call as follows:

format-message lint

Usage: format-message lint [options] [files...]

find message patterns in files and verify there are no obvious problems

Options:

-h, --help                  output usage information
-g, --generate-id [type]    generate missing ids from default message pattern (literal | normalized | underscored | underscored_crc32) [literal]
-l, --locale [locale]       BCP 47 language tags specifying the source default locale [en]
-t, --translations [path]   location of the JSON file with message translations, if specified, translations are also checked for errors
-f, --filename [filename]   filename to use when reading from stdin - this will be used in source-maps, errors etc [stdin]
-s, --style [style]         error output format (stylish | checkstyle | compact | html | jslint-xml | json | junit | tap | unix) [stylish]
-e, --extends [extends]     sets the rules that are used for linting (default | recommended | customrules) [default]'
-c, --customrules [path]    location of the custom rules file

Examples:

lint the src js files and translations

format-message lint -t i18n/pt-BR.json src/**/*.js

format-message extract

Usage: format-message extract [options] [files...]

find and list all message patterns in files

Options:

-h, --help                  output usage information
-g, --generate-id [type]    generate missing ids from default message pattern (literal | normalized | underscored | underscored_crc32) [literal]
-l, --locale [locale]       BCP 47 language tags specifying the source default locale [en]
-f, --filename [filename]   filename to use when reading from stdin - this will be used in source-maps, errors etc [stdin]
--format [format]           use the specified format instead of detecting from the --out-file extension (yaml | es6 | commonjs | json)
-o, --out-file [out]        write messages JSON object to this file instead of to stdout

Examples:

extract patterns from src js files, dump json to stdout. This can be helpful to get familiar with how --generate-id, --format and --locale change the json output.

format-message extract src/**/*.js

extract patterns from stdin, dump to file.

someTranspiler src | format-message extract -o locales/en.json

format-message transform

Usage: format-message transform [options] [files...]

find and replace message pattern calls in files with translations

By default this transform generates ids for messages that do not have an explicit id, and the result still relies on translations being properly configured with formatMessage.setup().

The --inline flag changes the behavior to inline one particular translation, and optimize the expression (often to a simple string literal). This requires passing --translations for any language other than the default.

Options:

-h, --help                            output usage information
-g, --generate-id [type]    generate missing ids from default message pattern (literal | normalized | underscored | underscored_crc32) [literal]
-l, --locale [locale]                 BCP 47 language tags specifying the target locale [en]
-t, --translations [path]             location of the JSON file with message translations
-e, --missing-translation [behavior]  behavior when --translations is specified, but a translated pattern is missing (error | warning | ignore) [error]
-m, --missing-replacement [pattern]   pattern to inline when a translated pattern is missing, defaults to the source pattern
-i, --inline                          inline the translation for the specified locale
--source-maps-inline                  append sourceMappingURL comment to bottom of code
-s, --source-maps                     save source map alongside the compiled code
-f, --filename [filename]             filename to use when reading from stdin - this will be used in source-maps, errors etc [stdin]
-o, --out-file [out]                  compile all input files into a single file
-d, --out-dir [out]                   compile an input directory of modules into an output directory
-r, --root [path]                     remove root path for source filename in output directory [cwd]

Examples:

create locale-specific client bundles with source maps

format-message transform -i src/**/*.js -s -l de -t translations.json -o dist/bundle.de.js
format-message transform -i src/**/*.js -s -l en -t translations.json -o dist/bundle.en.js
format-message transform -i src/**/*.js -s -l es -t translations.json -o dist/bundle.es.js
format-message transform -i src/**/*.js -s -l pt -t translations.json -o dist/bundle.pt.js
...

generate ids from default messages

format-message transform -d dist -r src src/*.js lib/*.js component/**/*.js

Inlined Messages

The examples provide sample transform --inline output. This output is not meant to be 100% exact, but to give a general idea of what the transform does.

Simple messages with no placeholders

formatMessage('My Collections')

// transforms to translated literal
"Minhas Coleções"

Simple string placeholders

formatMessage('Welcome, {name}!', { name: userName });

// messages with simple placeholders transforms to concatenated strings
"Bem Vindo, " + userName + "!" // Bem Vindo, Bob!

Complex number, date, and time placeholders

formatMessage('{ n, number, percent }', { n:0.1 });

// transforms to just the number call
formatMessage.number("en", 0.1, "percent") // "10%"


formatMessage('{ shorty, date, short }', { shorty:new Date() });

// transforms to just the date call
formatMessage.date("en", new Date(), "short") // "1/1/15"


formatMessage('You took {n,number} pictures since {d,date} {d,time}', { n:4000, d:new Date() });

// transforms to a sequence expression
(_params = { n:4000, d:new Date() },
  "You took " + formatMessage.number("en", _params.n) +
  " pictures since " + formatMessage.date("en", args["d"]) +
  " " + formatMessage.time("en", args["d"])
) // "You took 4,000 pictures since Jan 1, 2015 9:33:04 AM"

Complex string with select and plural in ES6

import formatMessage from 'format-message'

// using a template string for multiline, no interpolation
let formatMessage(`On { date, date, short } {name} ate {
  numBananas, plural,
       =0 {no bananas}
       =1 {a banana}
       =2 {a pair of bananas}
    other {# bananas}
  } {
  gender, select,
      male {at his house.}
    female {at her house.}
     other {at their house.}
  }`, {
  date: new Date(),
  name: 'Curious George',
  gender: 'male',
  numBananas: 27
})

// transforms to an expression
('On ' + formatMessage.date('en', new Date(), 'short') + ' ' +
'Curious George' + ' ate ' + (
  _s3 = 27, _n2 = +_s3,
    _n2 === 0 ? 'no bananas'
    : _n2 === 1 ? 'a banana'
    : _n2 === 2 ? 'a pair of bananas'
    : (formatMessage.number('en', 27) + ' bananas')
) + ' ' + (
  _s3 = 'male',
  _s3 === 'male' ? 'at his house.'
  : _s3 === 'female' ? 'at her house.'
  : 'at their house.'
))
// en-US: "On 1/1/15 Curious George ate 27 bananas at his house."

Current Optimizations

• Calls with no placeholders in the message become string literals.
• Calls with placeholders become an expression, and needed variables are added to the scope.
• Calls with an object literal for parameters inline the properties to where they are used, avoiding the object creation.

Note that if you have a complex or costly operation as one of the object property expressions, and that value has many placeholders in the message, you may perform the operation each time. To avoid this for costly operations, save the value in a variable beforehand and pass the variable into the parameters object instead.

License

This software is free to use under the MIT license. See the LICENSE-MIT file for license text and copyright information.