/ 
Text-PO-v0.9.0
River stage zero No dependents
/ po

NAME

po - GNU PO file manager

SYNOPSIS

po [ --debug|--nodebug, --verbose|--noverbose, -v, --help, --man]

# Show help
po --help

# Initialise a PO file
po --init --domain com.example.api --settings settings.json messages.po

po --init --domain com.example.api --lang fr_FR --settings settings.json \
   --pot template.pot --header "$(cat header.txt)" --version 0.2 --charset utf-8

po --sync --output file-to-be-synced.po source-file.po
po --sync --output file-to-be-synced.po source-file.mo
po --sync --output file-to-be-synced.po source-file.json

# Convert a PO file to JSON
po --as-json --output messages.json messages.po

# Convert JSON back to PO
po --as-po --output messages.po messages.json

# Dump the content of the file as a PO to the STDOUT
po --dump messages.po
po --dump messages.json
po --dump messages.mo

# Pre-process a PO file (resolve $include directives) and write to STDOUT
po --pp messages.po > messages.normalised.po

# Pre-process a PO file in place (requires --overwrite)
po --pp --overwrite messages.po

# Pre-process a PO file and write to a separate destination
po --pp --output /some/where/messages.normalised.po messages.po

# Add a msgid
po --add --msgid "Hello world!" --msgstr "Salut tout le monde !" messages.po

# Add an include directive to a .po file
po --add-include --file "some/file/to/include.po" messages.po

Options

Basic options:
--add                   Add an msgsid/msgstr entry in the po file
--add-include           Add an include directive to the po file
--as-po                 Write the file as a po file
--as-json               Write the po file as json on the STDOUT
--compile               Create a machine object file (.mo)
--domain                The po file domain
--dump                  Dump the PO file in a format suitable for a .po file
--init                  Create an initial po file such as .pot
--pre-process or --pp   Pre-process all possible include directive
--sync                  Synchronise a GNU PO file with another one

--after                 Specify the msgid to add the include directive after
--before                Specify the msgid to add the include directive before
--bugs-to               Sets the value for the meta field C<Report-Msgid-Bugs-To>
--charset               Sets the character encoding value in C<Content-Type>
--created-on            Sets the value for the meta field C<POT-Creation-Date>
--domain                The domain, such as C<com.example.api>
--encoding              Sets the value for the meta field C<Content-Transfer-Encoding>
--file                  Specify the file to include with C<--add-include>
--header                The string to be used as the header for the C<.po> file only.
--include               Enable the processing of include directives in the PO files
--noinclude             Disable the processing of include directives in the PO files
--lang                  The locale to use, such as en_US
--max-recurse           An unsigned integer to define the maximum recursion allowed when resolving include directives
--msgid                 The C<msgid> to add
--msgstr                The localised text to add for the given C<msgid>
--output                The output file
--output-dir            Output directory
--overwrite             Boolean. If true, this will allow overwriting existing file
--po-debug              Integer representing the debug value to be passed to L<Text::PO>
--pot                   The C<.pot> file to be used as a template in conjonction with --init
--project               Sets the value for the meta field C<Project-Id-Version>
--revised-on            Sets the value for the meta field C<PO-Revision-Date>
--settings              The settings json file containing default values
--team                  Sets the value for the meta field C<Language-Team>
--translator            Sets the value for the meta field C<Last-Translator>
--tz, --time-zone, --timezone Sets the time zone to use for the date in C<PO-Revision-Date> and C<POT-Creation-Date>
--version               Sets the version to be used in the meta field C<Project-Id-Version>

Standard options:
-h, --help              display this help and exit
-v                      display version information and exit
--debug                 Enable debug mode
--nodebug               Disable debug mode
--help, -?              Show this help
--man                   Show this help as a man page
--verbose               Enable verbose mode
--noverbose             Disable verbose mode

VERSION

v0.3.0

DESCRIPTION

This program, po, takes optional parameters and process GNU PO files.

GNU PO files are localisation or l10n files. They can be used as binary after been compiled, or they can be converted to JSON using this utility which then can read the JSON data instead of parsing the PO files, making it faster to load.

It can:

  • Convert .po files to and from JSON.

    po --as-json --output com.example.api.json com.example.api.po
po --as-json com.example.api.po # print to STDOUT
# Reading from a .mo file
po --as-json com.example.api.mo # print to STDOUT

po --as-po --output com.example.api.po com.example.api.json
po --as-po com.example.api.json # print to STDOUT
# Reading from a .mo file
po --as-po com.example.api.mo # print to STDOUT

  • Optionally read .mo files and export their content.

  • Pre-process PO files by resolving $include directives and rewriting a single, normalised PO file.

    po --pp com.example.api.po # print to STDOUT
po --pp --output com.example.api.po com.example.api.popp
# Normalise the PO file, and rewrite it in-place
po --pp --overwrite com.example.api.po

  • Compile a PO file to machine object (.mo) format.

    po --compile --output com.example.api.mo com.example.api.po
po --compile --output com.example.api.mo com.example.api.json

  • Add new localisation string to a .po, .json, or .mo file:

    po --add --msgid "Hello world!" --msgstr "Salut tout le monde !" com.example.api.po
po --add --msgid "Hello world!" --msgstr "Salut tout le monde !" com.example.api.json
po --add --msgid "Hello world!" --msgstr "Salut tout le monde !" com.example.api.mo

    You can specify at what position to add the new element with the --before and --after options. However, note that the elements are automatically sorted lexicographically for .mo files in line with GNU machine object requirements.

  • Add include directive to a .po file:

    po --add-include --file "some/file/to/include.po" target.po
po --add-include --file "some/file/to/include.po" --before "Some msgid" target.po
po --add-include --file "some/file/to/include.po" --after "Some msgid" target.po

    You can specify at what position to add the new element with the --before and --after options

  • Synchronise a PO file with another:

    po --sync --output file-to-be-synced.po source-file.po
po --sync --output file-to-be-synced.po source-file.mo
po --sync --output file-to-be-synced.po source-file.json

  • Initialise a PO file:

    po --init --domain com.example.api --output com.example.api.po
# print to STDOUT
po --init --domain com.example.api
# Loading default values from settings.json and template file template.pot
po --init --domain com.example.api --lang fr_FR --settings settings.json \
   --pot template.pot --header "$(cat header.txt)" --version 0.2 --charset utf-8

  • Dump the content of PO file

    po --dump com.example.api.po

    Any include directive will be resolved automatically unless --noinclude is used.

By default, po.pl reads from a single input file and writes either to a file specified with --output or to STDOUT. Some operations, such as pre-processing, may allow in-place rewriting when --overwrite is explicitly provided.

MODES

The tool operates in one of several modes. Only one main mode should be specified at a time.

--as-json

Read a PO (or MO) file and write its content as JSON.

--from-json

Read JSON produced by this tool and write a PO file.

--pp, --pre-process

Pre-process a PO file. This mode loads the PO file through Text::PO, processes any $include directives according to the include and max_recurse logic in Text::PO, and then writes back a single, flattened PO file.

When --pp is used:

  • If --output FILE is provided, the pre-processed result is written to FILE.

  • If --overwrite is provided and no --output is given, the input file is rewritten in place.

  • If neither --output nor --overwrite is given, the pre-processed result is written to STDOUT.

This makes --pp useful as a normalisation step in build pipelines or before handing PO files to third-party tools that do not understand $include directives.

OPTIONS

--add

Adds an msgid and msgstr pair to the po file

po --add --msgid "Hello!" --msgstr "Salut !" --output fr_FR/LC_MESSAGES/com.example.api.po

--as-json

Takes a po file and transcode it as a json po file

po --as-json --output fr_FR/LC_MESSAGES/com.example.api.json fr_FR.po

--as-po

Takes a .mo or .json file and transcode it to a po file

po --as-po --output fr_FR.po ./fr_FR/com.example.api.json

--bugs-to

The string to be used for the PO file header field Bugs-To

--charset

The PO file character set. This should be utf-8

--compile

Takes a po file and compiles it into a binary file wth extension mo

po --compile ./fr_FR/com.example.api.json
# Will create ./fr_FR/com.example.api.mo

--create-on

The PO file creation date. This can be an ISO 8601 date, or a unix timestamp, or even a relative date such as +1D. See "_set_get_datetime" in Module::Generic for more information

--domain

The PO file domain

po --init --domain com.example.api ./fr_FR/com.example.api.po

--dump

Dump the data contained as a GNU PO file to the STDOUT

po --dump /some/file.po >new_file.po
# Maybe?
diff /some/file.po new_file.po

--encoding

The PO file encoding. This defaults to 8bit. There is no reason to change this.

--header

The PO file meta information header

--include

Enable the processing of include directives in the PO files.

--noinclude

Disable the processing of include directives in the PO files.

--init

Init a new PO file

po --init --domain com.example.api --lang fr_FR ./fr_FR/com.example.api.po
# then you can convert it as a json file
po --as-json --output ./fr_FR/com.example.api.json ./fr_FR/com.example.api.po

--lang

The PO file locale language

po --init --domain com.example.api --lang fr_FR ./fr_FR/com.example.api.po

--max-recurse

po --pp --max-recurse N com.example.api.po

An unsigned integer, used along with --pp, to define the maximum recursion allowed when resolving include directives.

If omitted, Text::PO's default max_recurse is used.

--msgid

The localised string original text.

--msgstr

The localised string

--output

po --pp --output FILE original.po

Write the result to FILE instead of STDOUT. For --pp, this controls where the pre-processed PO is saved.

--output-dir

The output directory. For example to read multiple po file and create their related mo files under a given directory:

po --compile --output-dir ./en_GB/LC_MESSAGES en_GB.*.po

This will read all the po files for language en_GB as selected in write their related mo files under ./en_GB/LC_MESSAGES. This directory will be created if it does not exist. The domain will be derived from the po file.

--overwrite

Boolean. If true, this will allow overwriting existing file. Default is false

--po-debug

An integer value to set the level of debugging. Default is o (no debugging enabled)

--pot

The PO template file to use

--project

The PO file project name

--revised-on

The PO file revision date. This can be an ISO 8601 date, or a unix timestamp, or even a relative date such as +1D. See "_set_get_datetime" in Module::Generic for more information

--settings

The file path to the settings.json json file containing all the default values

This is convenient to set various default values rather than specifying each of of them as option

po --init --settings /some/where/settings.json --domain com.example.api --lang fr_FR ./fr_FR/com.example.api.po

--sync

Synchronise a PO file based on another (the source), adding any missing msgid and msgstr resources it finds in the source file.

For example, to synchronise a Japanese PO file based on its English equivalent:

po --sync --output ./locale/ja_JP/LC_MESSAGES/com.example.api.json ./locale/en_GB/LC_MESSAGES/com.example.api.json

--team

The team in charge of this PO file maintenance

--translator

The PO file Translator field containing the name of the person or group in charge of the translation for this file.

--tz, --time-zone, --timezone

The time zone to use in the PO file meta information header

--version

Displays this utility version number and quits.

--help

Print a short help message.

--debug

Enable debug mode with considerable verbosity

--nodebug

Disable debug mode.

--verbose

Enable verbose mode.

--noverbose

Disable verbose mode.

--man

Print this help as man page.

EXAMPLE

po [--dump, --debug|--nodebug, --verbose|--noverbose, -v, --help, --man] /some/file.po

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT

Copyright (c) 2020-2025 DEGUEST Pte. Ltd.