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

# html2po, po2html

Convert translatable items in HTML to the PO format. Insert translated text into HTML templates.

## Usage

    html2po [options] <html-src> <po>
    po2html [options] -i <po> -t <html-src> -o <html-dest>

Where:

<html-src> | is an HTML file or a directory of HTML files, source language
<html-dest> | is an HTML file or a directory of HTML files, translated to the target language
<po> | is a PO file or directory of PO files

Options (html2po):

`--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 htm, html, xhtml formats

`-x EXCLUDE, --exclude=EXCLUDE`

  exclude names matching EXCLUDE from input paths

`-o OUTPUT, --output=OUTPUT`

  write to OUTPUT in po, pot formats

`-S, --timestamp`

  skip conversion if the output file has newer timestamp

`-P, --pot`

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

`-u, --untagged`

  include untagged sections

`--keepcomments`

  preserve html comments as translation notes in the output

`--duplicates=DUPLICATESTYLE`

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

`--multifile=MULTIFILESTYLE`

  how to split po/pot files (single, toplevel or onefile) (default: ‘single’; if set to ‘onefile’, a single po/pot file will be written. ‘toplevel’ not used.)

Options (po2html):

`--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 htm, html, xhtml formats

`-t TEMPLATE, --template=TEMPLATE`

  read from TEMPLATE in htm, html, xhtml formats

`-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)

## Examples

    html2po -P site pot

This will find all HTML files (.htm, .html, .xhtml) in site, convert them to POT files and place them in pot.

You can create and update PO files for different languages using the pot2po command. For example, you can create PO files for a translation to Xhosa like this:

    pot2po -i pot -t site -o xh

This will merge the POT files in pot into the PO files in xh (if any).

And then, after editing the PO files in xh, you can generate the translated version of the web site like so:

    po2html -i xh -t site -o site-xh

All the PO translations in xh will be converted to HTML using HTML files in site as templates and outputting new translated HTML files in site-xh.

Should you prefer a single PO/POT file for your web site, you can create one like so:

    html2po -P --multifile=onefile site file.pot

When po2html is invoked with a single PO file as input, and a directory of template HTML files, it will produce one output file per template file. So to generate translated output files from a single PO file, invoke po2html like so:

    po2html -i xh.po -t site -o site-xh

In this example, xh.po is the translation file for Xhosa, site is the directory where the HTML files in the source language can be found, and site-xh is the directory where the translated HTML files will end up.

## Notes

The HTML format description gives more details on the format of the localisable HTML content and the capabilities of this converter.

Translator Comments

Use the `--keepcomments` option to preserve HTML comments and `data-translate-comment` attributes as translator notes in the output PO files. This helps translators understand the context of each string:

    html2po --keepcomments site pot

For more details on adding translator context, see Message Context (Disambiguation) in the HTML format documentation.

## Bugs

Some items end up in the msgid’s that should not be translated