Skip to content
Back to top
View this page
Edit this page

# toml2po

Added in version 3.16.0.

Converts TOML localization files to Gettext PO format.

## Usage

    toml2po [options] <toml> <po>
    po2toml [options] <po> <toml>

Where:

<toml> | is a valid TOML localisable file or directory of those files
<po> | is a directory of PO or POT files

Options (toml2po):

`--version`

  show program’s version number and exit

`-h, --help`

  show this help message and exit

`--manpage`

  output a manpage based on the help

`--progress=PROGRESS`

  show progress as: dots, none, bar, names, verbose

`--errorlevel=ERRORLEVEL`

  show errorlevel as: none, message, exception, traceback

`-i INPUT, --input=INPUT`

  read from INPUT in toml formats

`-x EXCLUDE, --exclude=EXCLUDE`

  exclude names matching EXCLUDE from input paths

`-o OUTPUT, --output=OUTPUT`

  write to OUTPUT in po, pot formats

`-t TEMPLATE, --template=TEMPLATE`

  read from TEMPLATE in toml formats

`-S, --timestamp`

  skip conversion if the output file has newer timestamp

`-P, --pot`

  output PO Templates (.pot) rather than PO files (.po)

`--duplicates=DUPLICATESTYLE`

  what to do with duplicate strings (identical source text): merge, msgctxt (default: ‘msgctxt’)

Options (po2toml):

`--version`

  show program’s version number and exit

`-h, --help`

  show this help message and exit

`--manpage`

  output a manpage based on the help

`--progress=PROGRESS`

  show progress as: dots, none, bar, names, verbose

`--errorlevel=ERRORLEVEL`

  show errorlevel as: none, message, exception, traceback

`-i INPUT, --input=INPUT`

  read from INPUT in po, pot formats

`-x EXCLUDE, --exclude=EXCLUDE`

  exclude names matching EXCLUDE from input paths

`-o OUTPUT, --output=OUTPUT`

  write to OUTPUT in toml formats

`-t TEMPLATE, --template=TEMPLATE`

  read from TEMPLATE in toml formats (required)

`-S, --timestamp`

  skip conversion if the output file has newer timestamp

`--threshold=PERCENT`

  only convert files where the translation completion is above PERCENT

`--fuzzy`

  use translations marked fuzzy

`--nofuzzy`

  don’t use translations marked fuzzy (default)

## Formats Supported

Check TOML format document to see which TOML features are supported.

## Examples

This example looks at roundtrip of TOML translations as well as recovery of existing translations.

First we need to create a set of POT files:

    toml2po -P i18n/en.toml pot/

The TOML file found in `i18n/en.toml` is converted to a Gettext POT file and placed in the `pot` directory.

If you are translating for the first time then you can skip the next step. If you need to recover your existing translations then we do the following:

    toml2po -t i18n/en.toml i18n/fr.toml po-fr/

Using the English TOML file found in `i18n/en.toml` and your existing French translation in `i18n/fr.toml` we create a set of PO files in `po-fr`. These will now have your translations. Please be aware that in order for that to work 100% you need to have both English and French at the same revision, if they are not you will have to review all translations.

You are now in a position to translate your recovered translations or your new POT files.

Once translated you can convert back as follows:

    po2toml -t i18n/en.toml po-fr/ i18n/fr.toml

Your translations found in the French PO directory, `po-fr/`, will be converted to TOML using the file in `i18n/en.toml` as a template and placing your new translations in `i18n/fr.toml`.

To update your translations simply redo the POT creation step and make use of pot2po to bring your translation up-to-date.