CLI
#
Installation- npm
- yarn
Add the following command to your package.json
scripts
:
We've built https://www.npmjs.com/package/@formatjs/cli that helps you extract messages from a list of files. It uses @formatjs/ts-transformer
under the hood and should be able to extract messages if you're declaring using 1 of the mechanisms below:
#
ExtractionFor example:
caution
You should always quote ("
or '
) your glob pattern (like "src/**/*"
) to avoid auto shell expansion of those glob, which varies depending on your shell (zsh
vs fish
vs bash
).
--format [path]
#
Path to a formatter file that controls the shape of JSON file from --out-file
.
The formatter file must export a function called format
with the signature.
This is especially useful to convert from our extracted format to a TMS-specific format.
See our builtin formatters for examples.
--out-file [path]
#
The target file path where the plugin will output an aggregated .json
file of allthe translations from the files
supplied. This flag will ignore --messages-dir
--id-interpolation-pattern [pattern]
#
If certain message descriptors don't have id, this pattern
will be used to automaticallygenerate IDs for them. Default to [contenthash:5]
. See https://github.com/webpack/loader-utils#interpolatename for sample patterns
--extract-source-location
#
Whether the metadata about the location of the message in the source file should be extracted. If true
, then file
, start
, and end
fields will exist for each extracted message descriptors. (default: false
)
--additional-component-names [comma-separated-names]
#
Additional component names to extract messages from, e.g: ['FormattedFooBarMessage']
. NOTE: By default we check for the fact that FormattedMessage
is imported from moduleSourceName
to make sure variable alias works. This option does not do that so it's less safe.
--additional-function-names [comma-separated-names]
#
Additional function names to extract messages from, e.g: ['$t']
.
--output-empty-json
#
Output file with empty [] if src has no messages. For build systems like bazel that relies on specific output mapping, not writing out a file can cause issues. (default: false
)
--ignore [files]
#
List of glob paths to not extract translations from.
--throws
#
Whether to throw an exception when we fail to process any file in the batch.
--pragma [pragma]
#
Parse specific additional custom pragma. This allows you to tag certain file with metadata such as project
. For example with this file:
and with option {pragma: "intl-meta"}
, we'll parse out // @intl-meta project:my-custom-project
into {project: 'my-custom-project'}
in the result file.
#
CompilationCompile extracted file from formatjs extract
to a react-intl consumable
JSON file. This also does ICU message verification. See Message Distribution for more details.
--format [path]
#
Path to a formatter file that converts <translation_file>
to Record<string, string>
so we can compile. The file must export a function named compile
with the signature:
This is especially useful to convert from a TMS-specific format back to react-intl format.
See our builtin formatters for examples.
--out-file <output>
#
The target file that contains compiled messages.
--ast
#
Whether to compile message into AST instead of just string. See Advanced Usage
--pseudo-locale <pseudoLocale>
#
Whether we should compile messages into pseudo locales instead. Available pseudo-locales:
Given the English message my name is {name}
Locale | Message |
---|---|
xx-LS | my name is {name}SSSSSSSSSSSSSSSSSSSSSSSSS |
xx-AC | MY NAME IS {name} |
xx-HA | [javascript]my name is {name} |
en-XA | ṁẏ ńâṁè íś {name} |
#
Folder CompilationBatch compile a folder with extracted files from formatjs extract
to a folder containing react-intl consumable JSON files. This also does ICU message verification. See Message Distribution for more details.
--format [path]
#
Path to a formatter file that converts <translation_file>
to Record<string, string>
so we can compile. The file must export a function named compile
with the signature:
This is especially useful to convert from a TMS-specific format back to react-intl format
--ast
#
Whether to compile message into AST instead of just string. See Advanced Usage
#
Builtin FormattersWe provide the following built-in formatters to integrate with 3rd party TMSes:
TMS | --format |
---|---|
Transifex's Structured JSON | transifex |
Smartling ICU JSON | smartling |
Lingohub | simple |
Phrase | simple |
Crowdin Chrome JSON | crowdin |
Lokalise Structured JSON | lokalise |
locize | simple |
SimpleLocalize | simple |
#
Custom FormattersYou can provide your own formatter by using our interfaces:
Take a look at our builtin formatter code for some examples.
#
Node API@formatjs/cli
can also be consumed programmatically like below: