Potools NPM | npm.io

Potools

A simple CLI utility to provide assistance with po-file based translations

Installation

To install globally use:

yarn global add potools or npm install -g potools

If you prefer to install this as a project dep then use:

yarn add potools --dev or npm install --save-dev potools

The command will be found in node_modules/.bin/potools.

Commands

debug

This command helps write out debug versions of pofile contents. It is both HTML and placeholder aware.

potools debug <potfile> [output] [format]

Options:
  --help    Show help                                                  [boolean]
  --format  The output format.
                             [choices: "unicode", "mirror"] [default: "unicode"]
  --output  Output path. If not provided outputs to stdout   [default: "stdout"]

Output Formats

There are two formats you can use:

unicode: converts input to use unicode characters.
mirror: converts input to use mirrored characters (recommended to be used via an RTL locale).

Placeholder Support

The debug command handles the following placeholder styles:

%(placeholder)s
%(placeholder)d
%s
%d
{placeholder}

See caveats for special handling of named placeholders for HTML substitution in the mirror format output.

Debug Examples:

potools debug ../bar/locale/templates/LC_MESSAGES/messages.pot

Will output to stdout in unicode format.

potools debug ../bar/locale/templates/LC_MESSAGES/messages.pot --format mirror

Will output to stdout in mirror format.

potools debug ../bar/locale/templates/LC_MESSAGES/messages.pot --format mirror --output ../test.txt

Will write the ouptut to ../test.txt.

Debug command caveats

The RTL debug locale generation (--format mirror) generally inverts input to emulate what an RTL translation will look like. It will also handle HTML by reversing parts of HTML AST during processing in order to keep a sane order of elements but reverse the order of text and HTML.

E.g: foo <a href="#whatevs">bar <span>test</span></a> becomes <a href="#whatevs"><span>ʇsǝʇ</span> ɹɐq</a> ooɟ.

When placeholders are used to substitute HTML, this will cause problems if the placeholders are inverted. To fix this placeholders that are prefixed with start or end and have a matching suffix will remain in their original placement order.

E.g: foo %(startSpan)sbar%(endSpan)s will become %(startSpan)sɹɐq%(endSpan)s ooɟ to preserve order.