message-format-inline
Write default messages inline. Optionally transpile translations.
Quick Start
npm install message-format-inline --save
adds the library to node_modules
. You can
then use it as follows:
var format = ; var message = ;
Your source code does not need to be transpiled in order to work properly, so
you can use format
in server-side code, and transpile your source for better
performance in repeated use on the client.
message-format-inline relies on Intl.NumberFormat
and Intl.DateTimeFormat
for formatting number
, date
, and time
arguments. If you are in an
environment missing these (like node <= 0.12, IE < 11, or Safari) you'll
need to use a polyfill.
Overview
The ICU Message Format is a great format for user-visible strings, and includes simple placeholders, number and date placeholders, and selecting among submessages for gender and plural arguments. The format is used in apis in C++, PHP, and Java.
message-format-inline provides a way to write your default (often English) messages as literals in your source, and then scrape out the default patterns and transpile your source with fast inline code for formatting the translated message patterns.
This relies on message-format for parsing and formatting ICU messages, and recast for transpiling the source code.
Supported ICU Formats
See message-format for supported ICU formats.
Quoting escaping rules
See the ICU site and message-format for details on how to escape special characters in your messages.
Loading locale data
message-format-inline supports plurals for all CLDR languages. Locale-aware
formatting of number, date, and time are delegated to the Intl
objects,
and select is the same across all locales. You don't need to load any extra
files for particular locales for message-format-inline.
API
format
var format = // or
Translate and format the message with the given pattern and arguments.
Parameters
pattern
is a properly formatted ICU Message Format pattern. A poorly formatted pattern will cause anError
to be thrown.- The pattern is used as a key into the
translate
function you provide in configuration, and is also used as the fallback if no translation is returned, ortranslate
has not been configured - If
pattern
is not a string literal, the function cannot be transpiled at build time.
- The pattern is used as a key into the
args
is an object containing the values to replace placeholders with. Required if the pattern contains placeholders.locales
is an optional string with a BCP 47 language tag, or an array of such strings.- The locales are also passed into the
translate
function and indicate the desired destination language. - If
locales
is not a string literal, the function cannot be transpiled at build time.
- The locales are also passed into the
format.setup
format
Configure format
behavior for subsequent calls. This should be called before
any code that uses format
.
Parameters
options
is an object containing the following config values:cache
is whether message, number, and date formatters are cached. Defaults totrue
locale
is the default locale to use when no locale is passed toformat
. Defaults to"en"
.translate(pattern, locales)
is a function to translate messages. It should return the pattern translated for the specified locale.pattern
is the message pattern to translate.locale
is a string with a BCP 47 language tag, or an array of such strings.
internal apis
format.number
, format.date
, and format.time
are used internally and are
not intended for external use. Because these appear in the transpiled code,
transpiling does not remove the need to properly define format
through
require
or import
.
Example Messages
The examples provide sample transpiler output. This output is not meant to be 100% exact, but to give a general idea of what the transpiler does.
Simple messages with no placeholders
// transpiles to translated literal"Minhas Coleções"
Simple string placeholders
; // non-trivial messages transpile to self-invoking function { return "Bem Vindo, " + args"name" + "!";}"pt-BR" name:'Bob' ;
number, date, and time placeholders
;// en-US: "You took 4,000 pictures since Jan 1, 2015 9:33:04 AM" ;// en-US: "10%" ;// en-US: "1/1/15"
Complex string with select and plural in ES6
// using a template string for multiline, no interpolationlet // en-US: "On 1/1/15 Curious George ate 27 bananas at his house."
CLI Tools
message-format lint
message-format lint [options] [files...]
Usage: find message patterns in files and verify there are no obvious problems
Options:
-h, --help output usage information
-n, --function-name [name] find function calls with this name [format]
-k, --key-type [type] derived key from source pattern literal|normalized|underscored|underscored_crc32 [underscored_crc32]
-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]
Examples:
lint the src js files, with __
as the function name used instead of format
message-format lint -n __ src/**/*.js
lint the src js files and translations
message-format lint -t i18n/pt-BR.json src/**/*.js
message-format extract
message-format extract [options] [files...]
Usage: find and list all message patterns in files
Options:
-h, --help output usage information
-n, --function-name [name] find function calls with this name [format]
-k, --key-type [type] derived key from source pattern (literal | normalized | underscored | underscored_crc32) [underscored_crc32]
-l, --locale [locale] BCP 47 language tags specifying the source default locale [en]
-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 --key-type
and --locale
change the json output.
message-format extract src/**/*.js
extract patterns from stdin
, dump to file.
someTranspiler src/*.js | message-format extract -o locales/en.json
message-format inline
message-format inline [options] [files...]
Usage: find and replace message pattern calls in files with translations
Options:
-h, --help output usage information
-n, --function-name [name] find function calls with this name [format]
-k, --key-type [type] derived key from source pattern (literal | normalized | underscored | underscored_crc32) [underscored_crc32]
-l, --locale [locale] BCP 47 language tags specifying the target locale [en]
-t, --translations [path] location of the JSON file with message translations
-i, --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
message-format inline src/**/*.js -s -l de -t translations.json -o dist/bundle.de.js
message-format inline src/**/*.js -s -l en -t translations.json -o dist/bundle.en.js
message-format inline src/**/*.js -s -l es -t translations.json -o dist/bundle.es.js
message-format inline src/**/*.js -s -l pt -t translations.json -o dist/bundle.pt.js
...
inline without translating multiple files that used var __ = require('mesage-format-inline')
message-format inline -d dist -r src -n __ src/*.js lib/*.js component/**/*.js
License
This software is free to use under the MIT license. See the LICENSE-MIT file for license text and copyright information.