Features¶

The Translate Toolkit is also a powerful API for writing translation and localisation tools, already used by our own and several other projects. See the base class section for more information.

Installation¶

This is a guide to installing the Translate Toolkit on your system. If the Translate Toolkit is already packaged for your system, this is probably the easiest way to install it. For several Linux distributions, the package might be available through your package manager. On Windows, we recommend using a virtual environment.

If your system already has the toolkit prepackaged, then please let us know what steps are required to install it.

Building¶

For build instructions, see the Building page.

Download¶

Download a stable released version. Or if you have a python environment, run pip install translate-toolkit. For those who need problems fixed, or who want to work on the bleeding edge, get the latest source from Git.

If you install through your distribution’s package manager, you should automatically have all the dependencies you need. If you are installing a version from Version Control, or from a source release, you should check the README file for information on the dependencies that are needed. Some of the dependencies are optional. The README file documents this.

Installing packaged versions¶

Get the package for your system:

The RPM package can be installed by using the following command:

$ rpm -Uvh translate-toolkit-1.0.1.rpm

To install a tar.bz2:

$ tar xvjf translate-toolkit-1.1.0.tar.bz2
$ cd translate-toolkit-1.1.0
$ su
$ ./setup.py install

On Debian (if you are on etch), just type the following command:

$ aptitude install translate-toolkit

If you are using an old Debian stable system, you might want to install the .tar.bz2 version. Be sure to install python and python development first with:

$ apt-get install python python-dev

Alternatively newer packages might be in testing.

Installing on Windows¶

On Windows we recommend that you install Translate Toolkit using a virtual environment. This makes installation clean and isolated.

Use the latest Python 3.9. Install virtualenvwrapper-win to simplify handling of virtualenvs.

Next times you need to use Translate Toolkit just remember to:

Installing from Git¶

If you want to try the bleeding edge, or just want to have the latest fixes from a stabilising branch then you need to use Git to get your sources:

$ git clone https://github.com/translate/translate.git

This will retrieve the master branch of the Toolkit. Further Git instructions are also available.

Once you have the sources you have two options, a full install:

$ su
$ ./setup.py install

or, running the tools from the source directory:

$ su
$ pip install -e .

Verify installed version¶

To verify which version of the toolkit you have installed run:

$ prop2po --version
prop2po 3.12.1

Cleaning up existing installation¶

To remove old versions of the toolkit which you might have installed without a virtual environment or without your package manager.

The following advice only applies to manual installation from a tarball.

$ python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"

$ rm -R /usr/local/lib/python3.9/dist-packages/translate

Converters¶

General Usage¶

The tools follow a general usage convention which is helpful to understand.

Input & Output¶

The last two arguments of your command are the input and output files/directories:

moz2po <input> <output>

You can of course still use the -i and -o options which allows you to reorder commands

moz2po -o <output> -i <input>

Error Reporting¶

All tools accept the option --errorlevel. If you find a bug, add this option and send the traceback to the developers.

moz2po <other-options> --errorlevel=traceback

Templates¶

If you are working with any file format and you wish to preserve comments and layout then use your source file as a template.

po2dtd -t <source-file> <input> <output>

This will use the files in <source-file> as a template, merge the PO files in <input>, and create new DTD files in <output>

If you ran this without the templates you would get valid DTD files but they would not preserve the layout or all the comments from the source DTD file

The same concept of templates is also used when you merge files.

pomerge -t <old> <fixes> <new>

This would take the <old> files merge in the <fixes> and output new PO files, preserving formatting, into <new>. You can use the same directory for <old> and <new> if you want the merges to overwrite files in <old>.

source2target¶

The converters all follow this convention:

Getting Help¶

The --help option will always list the available commands for the tool.

moz2po --help

android2po¶

Converts Android resource files to Gettext PO format.

Usage¶

android2po [options] <android> <po>

Where:

Examples¶

These examples demonstrate the use of android2po:

to simply convert strings-en.xml to en.po.

To convert a source and target Android resources files into a PO file:

strings-en.xml contains the template resource and strings-ca.xml the localised resource strings.

csv2po¶

Convert between CSV (Comma Separated Value) files and the PO format. This is useful for those translators who can only use a Spreadsheet, a modern spreadsheet can open CSV files for editing. It is also useful if you have other data such as translation memory in CSV format and you wish to use it with your PO translations.

If you are starting out with your own CSV files (not created by po2csv), take note of the assumptions of the column layout explained below.

Usage¶

csv2po [options] <csv> <po>
po2csv [options] <po> <csv>

Where:

Options (csv2po):

Options (po2csv):

CSV file layout¶

The resultant CSV file has the following layout

The layout can be customized by --columnorder, you can add, or remove columns using that as well, for example --columnorder=context,source,target.

Examples¶

These examples demonstrate the use of csv2po:

po2csv -P pot csv

We use the -P option to recognise POT files found in pot and convert them to CSV files placed in csv:

csv2po csv po

Convert CSV files in csv to PO files placed in po:

csv2po --charset=windows-1250 -t pot csv po

User working on Windows will often return files encoded in everything but Unicode. In this case we convert CSV files found in csv from windows-1250 to UTF-8 and place the correctly encoded files in po. We use the templates found in pot to ensure that we preserve formatting and other data. Note that UTF-8 is the only available destination encoding.

csv2po --columnorder=location,target,source fr.csv fr.po

In case the CSV file has the columns in a different order you may use --columnorder.

Bugs¶

csv2tbx¶

Convert between CSV (Comma Separated Value) files and the TBX format for terminology exchange.

Usage¶

csv2tbx [--charset=CHARSET] [--columnorder=COLUMNORDER] <csv> <tbx>

Where:

Options (csv2tbx):

CSV file layout¶

The CSV file is expected to have three columns (separated by commas, not other characters like semicolons), of which the default layout is

Examples¶

These examples demonstrate the use of csv2tbx:

csv2tbx terms.csv terms.tbx

to simply convert terms.csv to terms.tbx.

To convert a directory recursively to another directory with the same structure of files:

csv2tbx csv-dir tbx-target-dir

This will convert CSV files in csv-dir to TBX files placed in tbx-target-dir.:

csv2tbx --charset=windows-1250 csv tbx

Users working on Windows will often return files in encoding other the Unicode based encodings. In this case we convert CSV files found in csv from windows-1250 to UTF-8 and place the correctly encoded files in tbx. Note that UTF-8 is the only available destination encoding.

Two column CSV¶

csv2tbx --columnorder=source,target foo.csv foo.tbx

Notes¶

For conformance to the standards and to see which features are implemented, see CSV and TBX.

flatxml2po¶

Converts flat XML (.xml) files to Gettext PO format, a simple monolingual and single-level XML.

Usage¶

flatxml2po [options] <xml> <po>
po2flatxml [options] <po> <xml> [-t <base-xml>]

Where:

Options (flatxml2po):

Options (po2flatxml):

Formats Supported¶

Check flat XML format document to see to which extent the XML format is supported.

Examples¶

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

First we need to create a set of POT files.:

flatxml2po -P lang/en pot/

All .xml files found in the lang/en directory are converted to Gettext POT files 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:

flatxml2po -t lang/en lang/zu po-zu/

Using the English XML files found in lang/en and your existing Zulu translation in lang/zu we create a set of PO files in po-zu. These will now have your translations. Please be aware that in order for that to work 100% you need to have both English and Zulu 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:

po2flatxml -t lang/en po-zu/ lang/zu

Your translations found in the Zulu PO directory, po-zu, will be converted to XML using the files in lang/en as templates and placing your new translations in lang/zu.

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

Limitations¶

Indentation only supports spaces (specified with --indent greater than zero) or flattened (no indentation, everything on a single line; specified with --indent set to zero). Tabs are not supported using po2flatxml.

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:

Options (html2po):

Options (po2html):

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.

Bugs¶

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

ical2po¶

New in version 1.2.

Converts iCalendar (*.ics) files to Gettext PO format.

Usage¶

ical2po [options] <ical> <po>
po2ical [options] -t <ical> <po> <ical>

Where:

Options (ical2po):

Options (po2ical):

Examples¶

This example looks at roundtrip of iCalendar translations. While you can do recovery of translations, its unlikely that you will ever need to do that.

First we need to create a set of POT files.

ical2po -P ical.ics ical.pot

The ical.ics file is converted to Gettext POT files called ical.pot. Directories of iCalendar files can also be processed.

Begin translating the ical.pot file by first copying it to make a PO file.

cp ical.pot ical-af.po

You are now in a position to translate the file ical-af.po in your favourite translation tool.

Once translated you can convert back as follows:

po2ical -t ical.ics ical-af.po ical-af.ics

Your translations found in the Afrikaans PO file, ical-af.po, will be converted to .ics using the file ical.ics as a template and creating your newly translated .ics file ical-af.ics.

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

Notes¶

The converter will only process events in the calendar file, the file itself can contain many other things that could be localisable. Please raise a bug if you want to extract additional items.

The converter does not make use of the LANGUAGE attribute which is permitted in the format. The LANGUAGE attribute does not aid multilingualism in this context so is ignored.

The converter could conceivably also process vCard files, but this has not been implemented for lack of a clear need. Please raise a bug with an example if you have such a file that could benefit from localisation.

ini2po¶

Converts .ini files to Gettext PO format.

Usage¶

ini2po [options] <ini> <po>
po2ini [options] -t <ini> <po> <ini>

Where:

Options (ini2po):

Options (po2ini):

Formats Supported¶

INI files need to be organized into separate languages per file and in the following format:

[Section]


  ; a comment


  a = a string

Comment marked with the hash symbol (#) are also allowed, and the colon (:) is also accepted as key-value delimiter:

[Section]


  # another comment


  b : a string

This variants in comment marks and key-value delimiters can be mixed in one single INI file:

[Section]
; a comment
a = a string
# another comment
b : a string
c:'other example with apostrophes'
d:"example with double quotes"

The spacing between the key-value delimiter and the key, and the between the value and the key-value delimiter is not important since the converter automatically strips the blank spaces.

NOTE:

NOTE:

#: [Section]c
msgid "'other example with apostrophes'"
msgstr ""
#: [Section]d
msgid "\"example with double quotes\""
msgstr ""

Examples¶

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

First we need to create a set of POT files.

ini2po -P ini/ pot/

All .ini files found in the ini/ directory are converted to Gettext POT files 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:

ini2po -t lang/ zu/ po-zu/

Using the English .ini files found in lang/ and your existing Zulu translation in zu/ we create a set of PO files in po-zu/. These will now have your translations. Please be aware that in order for the to work 100% you need to have both English and Zulu 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:

po2ini -t lang/ po-zu/ zu/

Your translations found in the Zulu PO directory, po-zu/, will be converted to .ini using the files in lang/ as templates and placing your newly translated .ini files in zu/.

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

Issues¶

We do not extract comments from .ini files. These are sometimes needed as developers provide guidance to translators in these comments.

json2po¶

Converts .json files to Gettext PO format.

Usage¶

json2po [options] <json> <po>
po2json [options] -t <json> <po> <json>

Where:

Options (json2po):

Options (po2json):

Examples¶

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

First we need to create a set of POT files.

json2po -P json/ pot/

All .json files found in the json/ directory are converted to Gettext POT files 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:

json2po -t lang/ zu/ po-zu/

Using the English .json files found in lang/ and your existing Zulu translation in zu/ we create a set of PO files in po-zu/. These will now have your translations. Please be aware that in order for the to work 100% you need to have both English and Zulu 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:

po2json -t lang/ po-zu/ zu/

Your translations found in the Zulu PO directory, po-zu/, will be converted to .json using the files in lang/ as templates and placing your newly translated .json files in zu/.

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

md2po, po2md¶

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

Usage¶

md2po [options] <md-src> <po>
po2md [options] -i <po> -t <md-src> -o <md-dest>

Where:

Options (md2po):

Options (po2md):

Examples¶

md2po -P source-md-dir pot

This will find all Markdown files (.md, .markdown, .txt, .text) in source-md-dir, convert them to POT files (that is, extract all translatable content) and place them in pot.

See the pot2po command for more information about how to create PO files from the POT files, and to update existing PO files when the POT files have changed.

Suppose you have created PO files for translation to Xhosa and placed them in the directory xh. You can then generate the translated version of the Markdown documents like so:

po2md -i xh -t source-md-dir -o xh-md-dir

All the PO translations in xh will be converted to Markdown using Markdown files in source-md-dir as templates and outputting new translated Markdown files in xh-md-dir.

Should you prefer a single PO/POT file for your collection of Markdown files, this is how to do it:

md2po -P --multifile=onefile source-md-dir file.pot

And similarly, to generate multiple translated output files from a single PO file, invoke po2md like so:

po2md -i xh.po -t source-md-dir -o xh-md-dir

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

Notes¶

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

moz2po¶

moz2po converts Mozilla files to PO files. It wraps converters that handle .properties, .dtd and some strange Mozilla files. The tool can work with files from Mozilla’s Mercurial repository. The tools thus provides a complete roundtrip for Mozilla localisation using PO files and PO editors.

NOTE:

Usage¶

moz2po [options] <dir> <po>
po2moz [options] <po> <dir>

Where:

Options (moz2po):

Options (po2moz):

Examples¶

Creating POT files¶

SEE ALSO:

After extracting the en-US l10n files, you can run the following command:

moz2po -P l10n/en-US pot

This creates a set of POT (-P) files in the pot directory from the Mozilla files in l10n/en-US for use as PO Templates.

If you want to create a set of POT files with another base language try the following:

moz2po -P l10n/fr-FR fr-pot

This will create a set of POT files in fr-pot that have French as your source language.

Creating PO files from existing non-PO translations¶

If you have existing translations (Mozilla related or other Babelzilla files) and you wish to convert them to PO for future translation then the following generic instructions will work:

moz2po -t en-US af-ZA af-ZA_pofiles

This will combine the untranslated template en-US files from en-US combine them with your existing translations in af-ZA and output PO files to af-ZA_pofiles.

moz2po -t l10n/fr l10n/xh po/xh

For those who are not English fluent you can do the same with another languages. In this case msgid will contain the French text from l10n/fr. This is useful for translating where the translators other languages is not English but French, Spanish or Portuguese. Please make sure that the source languages i.e. the msgid language is fully translated as against en-US.

Creating Mercurial ready translations¶

po2moz -t l10n/en-US po/xh l10n/xh

Create Mozilla files using the templates files in l10n/en-US (see above for how to create them) with PO translations in po/xh and output them to l10n/xh. The files now in l10n/xh are ready for submission to Mozilla and can be used to build a language pack or translated version of Mozilla.

Issues¶

You can perform the bulk of your work (99%) with moz2po.

Localisation of XHTML is not yet perfect, you might want to work with the files directly.

Issue 203 tracks the outstanding features which would allow complete localisation of Mozilla including; all help, start pages, rdf files, etc. It also tracks some bugs.

Accesskeys don’t yet work in .properties files and in several cases where the Mozilla .dtd files don’t follow the normal conventions, for example in security/manager/chrome/pippki/pref-ssl.dtd.po. You might also want to check the files mentioned in this Mozilla bug 329444 where mistakes in the DTD-definitions cause problems in the matching of accelerators with the text.

You might want to give special attention to the following files since it contains customisations that are not really translations.

Also, all width, height and size specifications need to be edited with feedback from testing the translated interfaces.

There are some constructed strings in the Mozilla code which we can’t do much about. Take good care to read the localisation notes. For an example, see mail/chrome/messenger/downloadheaders.dtd.po. In that specific file, the localisation note from the DTD file is lost, so take good care of those.

The file extension of the original Mozilla file is required to tell the Toolkit how to do the conversion. Therefore, a file like foo.dtd must be named foo.dtd.po in order to po2moz to recognise it as a DTD file.

odf2xliff and xliff2odf¶

Convert OpenDocument (ODF) files to XLIFF localization files. Create translated ODF files by combining the original ODF files with XLIFF files containing translations of strings in the original document.

XLIFF is the XML Localization Interchange File Format developed by OASIS (The Organization for the Advancement of Structured Information Standards) to allow translation work to be standardised no matter what the source format and to allow the work to be freely moved from tool to tool.

If you are more used to software translation or l10n, you might want to read a bit about Document translation. This should help you to get the most out of translating ODF with XLIFF.

Usage¶

odf2xliff [options] <original_odf> <xliff>
xliff2odf [options] -t <original_odf> <xliff> <translated_odf>

Where:

Options (odf2xliff):

Options (xliff2odf):

Examples¶

odf2xliff english.odt english_français.xlf

Create an XLIFF file from an ODT file (the source ODF file could also be any of the other ODF files, including ODS, ODG, etc.).

xliff2odf -t english.odt english_français.xlf français.odt

Using english.odt as the template document, and english_français.xlf as the file of translations, create a translated file français.odt.

Bugs¶

This filter is not yet extensively used – we appreciate your feedback. For more information on conformance to standards, see the XLIFF or OpenDocument Format pages.

oo2po¶

Convert between OpenOffice.org GSI/SDF files and the PO format. This tool provides a complete roundtrip; it preserves the structure of the GSI file and creates completely valid PO files.

oo2xliff will convert the SDF files to XLIFF format.

Usage¶

oo2po [options] <sdf> <output>
po2oo [options] [-t <en-US.sdf>] -l <targetlang> <input> <sdf|output>

or for XLIFF files:

oo2xliff [options] -l <targetlang> <sdf> <output>
xliff2oo [options] [-t <en-US.sdf>] -l <targetlang> <input> <sdf|output>

Where:

Options (oo2po and oo2xliff):

Options (po2oo and xliff2oo):

Examples¶

These examples demonstrate most of the useful invocations of oo2po:

Creating POT files¶

oo2po -P en-US.sdf pot

Extract messages from en-US.sdf and place them in a directory called pot. The -P option ensures that we create POT files instead of PO files.

oo2po -P --source-language=fr fr-FR.sdf french-pot

Instead of creating English POT files we are now creating POT files that contain French in the msgid. This is useful for translators who are not English literate. You will need to have a fully translated sdf in the source language.

Creating PO files from existing work¶

oo2po --duplicates=merge -l zu zu-ZA.sdf zulu

Extract all existing Zulu (zu) messages from zu-ZA.sdf and place them in a directory called zulu. If you find duplicate messages in a file then merge them into a single message (This is the default behaviour for traditional PO files). You might want to use pomigrate2 to ensure that your PO files match the latest POT files.:

cat GSI_af.sdf GSI_xh.sdf > GSI_af-xh.sdf
oo2po --source-language=af -l xh GSI_af-xh.sdf af-xh-po

Here we are creating PO files with your existing translations but a different source language. Firstly we combine the two SDF files. Then oo2po creates a set of PO files in af-xh-po using Afrikaans (af) as the source language and Xhosa (xh) as the target language from the combined SDF file GSI_af-xh.sdf

Creating a new GSI/SDF file¶

po2oo -l zu zulu zu_ZA.sdf

Using PO files found in zulu create an SDF files called zu_ZA.sdf for language zu:

po2oo -l af -t en-US.sdf --nofuzzy --keeptimestamp --filteraction=exclude-serious afrikaans af_ZA.sdf

Create an Afrikaans (af) SDF file called af_ZA.sdf using en-US.sdf as a template and preserving the timestamps within the SDF file while also eliminating any serious errors in translation. Using templates ensures that the resultant SDF file has exactly the same format as the template SDF file. In an SDF file each translated string can have a timestamp attached. This creates a large amount of unuseful traffic when comparing version of the SDF file, by preserving the timestamp we ensure that this does not change and can therefore see the translation changes clearly. We have included the nofuzzy option (on by default) that prevent fuzzy PO messages from getting into the SDF file. Lastly the filteraction option is set to exclude serious errors: variables failures and translated XML will be excluded from the final SDF.

helpcontent2¶

The escaping of helpcontent2 from SDF files was very confusing, issue 295 implemented a fix that appeared in version 1.1.0 (All known issues were fixed in 1.1.1). Translators are now able to translate helpcontent2 with clean escaping.

php2po¶

Converts PHP localisable string arrays to Gettext PO format.

Usage¶

php2po [options] <php> <po>
po2php [options] <po> <php>

Where:

Options (php2po):

Options (po2php):

Formats Supported¶

Check PHP format document to see to which extent the PHP format is supported.

Examples¶

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

First we need to create a set of POT files.:

php2po -P lang/en pot/

All .php files found in the lang/en directory are converted to Gettext POT files 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:

php2po -t lang/en lang/zu po-zu/

Using the English PHP files found in lang/en and your existing Zulu translation in lang/zu we create a set of PO files in po-zu. These will now have your translations. Please be aware that in order for that to work 100% you need to have both English and Zulu 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:

po2php -t lang/en po-zu/ lang/zu

Your translations found in the Zulu PO directory, po-zu, will be converted to PHP using the files in lang/en as templates and placing your new translations in lang/zu.

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

po2tmx¶

Convert Gettext PO files to a TMX translation memory file. TMX is the Translation Memory eXchange format developed by OSCAR.

[*]

OSCAR (Open Standards for Container/Content Allowing Re-use), a special interest group of the now defunct LISA (Localization Industry Standards Association). The Gala LISA OSCAR Standards page has more details on the possible future for the standards.

If you are interested in po2tmx, you might also be interested in posegment that can be used to perform some automated segmentation on sentence level.

Usage¶

po2tmx [options] --language <target> <po> <tmx>

Where:

Options:

Examples¶

po2tmx -l xh browser.po browser.tmx

Use the Xhosa (xh) translations in the PO file browser.po to create a TMX file called browser.tmx

Bugs and issues¶

Markup stripping¶

po2tmx conforms to TMX v1.4 without stripping markup. See the TMX conformance page for more details.

It has not been widely tested so your mileage may vary.

TMX and PO in OmegaT¶

In some tools, like OmegaT, PO files are parsed without expanding escaped sequences, even though such tools use TMX for translation memory. Keep this in mind when using po2tmx, because po2tmx converts \n and \t to newlines and tabs in the TMX file. If such a TMX file is used while translating PO files in OmegaT, matching will be less than 100%.

In other tools, such as Swordfish, the PO comment “no-wrap” is interpreted in the same way as the equivalent function in XML, which may also lead to mismatches if TMXes from po2tmx are used.

There is nothing wrong with po2tmx, but if used in conjunction with tools that handle PO files differently, it may lead to less than perfect matching.

Tips¶

TMX with only unique segments¶

To create a TMX with no duplicates (in other words, only unique strings), use msgcat to first create a large PO file with non-uniques removed.

po2wordfast¶

Convert Gettext PO files to a Wordfast Translation Memory translation memory file.

Wordfast is a popular Windows based computer-assisted translation tool.

Usage¶

po2wordfast [options] --language <target> <po> <wordfast>

Where:

Options:

Examples¶

po2wordfast -l xh-ZA browser.po browser.txt

Use the Xhosa (xh-ZA) translations in the PO file browser.po to create a Wordfast translation memory file called browser.txt

pot2po¶

Convert a Gettext PO Template file to a PO file and merge in existing translations if they are present. A translation memory (compendium) can also be used for fuzzy matching. This corresponds to a large extent with the program “msgmerge” from the gettext package.

NOTE:

Usage¶

pot2po [options] <pot> <po>

Where:

Options:

Examples¶

pot2po -t zu-1.0.1 pot-2.0.2 zu-2.0.2

Here we are initialising the PO files in zu-2.0.2 based on the POT files in pot-2.0.2. We are using the old translations in zu-1.0.1 as templates so that we can reuse our existing translations in the new files.

pot2po can also be used to update against newer templates an existing translation file in a format different than Gettext PO, for example XLIFF:

pot2po -t af.xlf -i templates.xlf -o updated-af.xlf

If the POT files have undergone major reshuffling then you may want to use pomigrate2 which can now use pot2po as its merging backend. pomigrate2 will do its best to migrate your files to the correct locations before merging. It will also make use of a compendium if requested.

pot2po --tm=compendium.po --similarity=60 -t xh-old pot xh-new

With this update we are using compendium.po as a translations memory (you can make use of other files such as TMX, etc). We will accept any match that scores above 60%.

Merging¶

It helps to understand when and how pot2po will merge. The default is to follow msgmerge’s behaviour but we add some extra features with fuzzy matching:

Performance¶

Fuzzy matches are usually of good quality. Installation of the python-Levenshtein package will speed up fuzzy matching. Without this a Python based matcher is used which is considerably slower.

Bugs¶

prop2po¶

Convert between Java property files (.properties) and Gettext PO format.

Note: this tool completely eliminates the need for native2ascii as po2prop does the correct escaping to the Latin1 encoding that is needed by Java.

The following other formats are also supported via the –personality parameter:

Usage¶

prop2po [options] <property> <po>
po2prop [options] -t <template> <po> <property>

Where:

Options (prop2po):

Options (po2prop):

Examples¶

These examples demonstrate most of the useful invocations of prop2po:

Creating POT files¶

prop2po -P properties pot

Extract messages from properties directory and place them in a directory called pot. The -P option ensures that we create POT files instead of PO files.:

prop2po -P file.properties file.pot

Extract messages from file.properties and place them in file.pot.

Creating PO files from existing work¶

prop2po --duplicates=msgctxt -t reference zu zu-po

Extract all existing Zulu messages from zu directory and place the resultant PO files in a directory called zu-po. If you find duplicate messages in a file then use Gettext’s mgsctxt to disambiguate them. During the merge we use the .properties files in reference as templates and as the source of the English text for the msgid. Once you have your PO files you might want to use pomigrate2 to ensure that your PO files match the latest POT files.

Creating .properties files from your translations¶

po2prop -t reference zu-po zu

Using our translations found in zu-po and the templates found in reference we create a new set of property files in zu. These new property files will look exactly like those found in the templates, but with the text changed to the translation. Any fuzzy entry in our PO files will be ignored and any untranslated item will be placed in zu in English. The .properties file created will be based on the Java specification and will thus use escaped Unicode. Where:

ṽḁḽṻḝ

Will appear in the files as:

\u1E7D\u1E01\u1E3D\u1E7B\u1E1D

To get output as used by Mozilla localisation do the following:

po2prop --personality=mozilla -t reference zu-po zu

This will do exactly the same as above except that the output will now appear as real Unicode characters in UTF-8 encoding.

Doing away with native2ascii¶

The native2ascii command is the traditional tool of property file localisers. With prop2po there is no need to use this command or to ever work directly with the escaped Unicode.

If you are working mostly with Gettext PO files then this is a double benefit as you can now use your favourite PO editor to translate Java applications. Your process would now look like this:

prop2po some.properties some.po

Firstly create a PO file that you can translate. Now translate it in your favourite PO editor.:

po2prop -t some.properties some.po some-other.properties

Using the original properties file as a template we preserve all layout and comments, combined with your PO translation we create a new translate properties file. During this whole process we have not needed to understand or process any escaping prop2po and po2prop handle that all automatically.

If you have existing translations you can recover them as follows:

prop2po -t some.properties translations.properties translations.po

This takes the default English properties file and combines it with your translate properties file and created a PO file. You now continue translating using your PO file.

rc2po¶

Converts Windows Resource .rc files to Gettext PO format.

Usage¶

rc2po [options] <rc> <po>
po2rc [options] -t <rc> <po> <rc>

Where:

Options (rc2po):

Options (po2rc):

Formats Supported¶

NOTE:

Examples¶

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

First we need to create a set of POT files.

rc2po -P lang/ pot/

All .rc files found in the lang/ directory are converted to Gettext POT files 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 recovery your existing translations then we do the following:

rc2po -t lang zu po-zu/

Using the English .rc files found in lang and your existing Zulu translation in zu we create a set of PO files in po-zu. These will now have your translations. Please be aware that in order for the to work 100% you need to have both English and Zulu at the same revision, if they are not you will have to review all translations. Also the .rc files may be in different encoding, we cannot at the moment process files of different encodings and assume both are in the same encoding supplied.

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

Once translated you can convert back as follows:

po2rc -t lang/ po-zu/ zu/

Your translations found in the Zulu PO directory, po-zu, will be converted to .rc using the files in lang/ as templates and placing your new translations in zu/.

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

Issues¶

If you are recovering translation using rc2po -t en.rc xx.rc xx.po then both en.rc and xx.rc need to be in the same encoding.

There might be problems with MENUs that are deaply nested.

resx2po¶

Converts .Net Resource (.resx) files to Gettext PO format, a monolingual file format used in Microsoft .Net Applications.

Usage¶

resx2po [options] <resx> <po>
po2resx [options] <po> <resx> -t <resx>

Where:

Options (resx2po):

Options (po2resx):

Examples¶

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

First we need to create a set of POT files

resx2po -P resx/ pot/

All .resx files found in the resx/ directory are converted to Gettext POT files 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

resx2po zu/ po-zu/ -t lang/

Using the English .resx files found in lang/ and your existing Zulu translation in zu/ we create a set of PO files in po-zu/. These will now have your translations. Please be aware that in order for the to work 100% you need to have both English and Zulu 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:

po2resx po-zu/ zu/ -t lang/

Your translations found in the Zulu PO directory, po-zu/, will be converted to .resx using the files in lang/ as templates and placing your newly translated .resx files in zu/.

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

sub2po¶

sub2po allows you to use the same principles of PO files with Subtitles. In PO only items that change are marked fuzzy and only new items need to be translated, unchanged items remain unchanged for the translation.

Usage¶

sub2po [options] <foo.srt> <foo.po>
po2sub [options] [-t <foo.srt>] <XX.po> <foo-XX.srt>

Where:

Options (sub2po):

Options (po2sub):

Examples¶

To create the POT files is simple:

sub2po -P SUBTITLE_FILE subtitles.pot

A translator would copy the POT file to their own PO file and then create translations of the entries. If you wish to create a PO file and not a POT file then leave off the -P option.

To convert back:

po2sub -t SUBTITLE_FILE   subtitles-XX.po  subtitles-XX.srt

Translating¶

Translate as normal. However, see the issues mentioned at Subtitles.

Bugs¶

There might be some issues with encodings, since the srt files don’t specify them. We assume files to be encoded in UTF-8, so a conversion should solve this easily. Note that most of the handling of the srt files come from gaupol.

symb2po¶

New in version 1.3.

Converts Symbian-style translation files to PO files and vice versa. The Symbian translation files currently have a strong Buddycloud flavour, but the tools will be made more general as the need arises.

Usage¶

symb2po [options] [-t <target_lang_symb>] <source_lang_symb> <po>
po2symb [options] -t <target_lang_symb> <po> <target_lang_symb>

Where:

Options (symb2po):

Options (po2symb):

Examples¶

symb2po¶

The most common use of symb2po, is to generate a POT (PO template) file from the English translation (note that the tool currently expects the Symbian translation file to end with the extension .r01, which is the code for English translation files). This file then serves as the source document from which all translations will be derived.

To create a POT file called my_project.pot from the source Symbian translation file my_project.r01, the following is executed:

symb2po my_project.r01 my_project.pot

In order to re-use existing translations in the Symbian translation format, symb2po can merge that translation into the source Symbian translation to produce a translated PO file. The existing Symbian translation file is specified with the -t flag.

To create a file called my_project-en-fr.po (this is not the recommended PO naming convention) from the source Symbian translation file my_project.r01 and its French translation my_project.r02, execute:

symb2po -t my_project.r02 my_project.r01 my_project-en-fr.po

NOTE:

po2symb¶

The po2symb tool is used to extract the translations in a PO into a template Symbian translation file. The template Symbian translation file supplies the “shape” of the generated file (formatting and comments).

In order to produce a French Symbian translation file using the English Symbian translation file my_project.r01 as a template and the PO file my_project-en-fr.po (this is not the recommended PO naming convention) as the source document, execute:

po2symb -t my_project.r01 my_project-en-fr.po my_project.r02

Notes¶

The tools won’t touch anything appearing between lines marked as:

// DO NOT TRANSLATE

The string r_string_languagegroup_name is used to set the Language-Team PO header field.

The Symbian translation header field Author is used to set the Last-Translator PO header field.

Issues¶

The file format is heavily tilted towards the Buddycould implementation

The tools do nothing with the Name and Description Symbian header fields. This means that po2symb will just copy the values in the supplied template. So you might see something such as:

Description : Localisation File : English

in a generated French translation file.

Bugs¶

Probably many, since this software hasn’t been tested much yet.

tbx2po¶

Convert between TermBase eXchange (.tbx) glossary format and Gettext PO format.

Usage¶

tbx2po <tbx> <po>

Where:

Options (tbx2po):

Examples¶

These examples demonstrate the use of tbx2po:

tbx2po terms.tbx terms.po

to simply convert terms.tbx to terms.po.

To convert a directory recursively to another directory with the same structure of files:

tbx2po tbx-dir po-target-dir

This will convert TBX files in tbx-dir to PO files placed in po-target-dir.

Notes¶

For conformance to the standards and to see which features are implemented, see PO Files and TBX.

tiki2po¶

Converts TikiWiki language.php files to Gettext PO format.

Usage¶

tiki2po [options] <tiki> <po>
po2tiki [options] <po> <tiki>

Where:

Options (tiki2po):

Options (po2tiki):

Examples¶

These examples demonstrate the use of tiki2po:

tiki2po language.php language.po

Convert the tiki language.php file to .po:

po2tiki language.po language.php

Convert a .po file to a tiki language.php file

Notes¶

ts2po¶

Convert Qt .ts localization files to Gettext .po format files using ts2po and convert the translated PO Files files back to Qt .ts using po2ts.

The Qt toolkit comes with a localization application, Qt Linguist, however you might wish to standardise on one localization tool. ts2po allows you to standardise on the PO format and PO related tools.

NOTE:

WARNING:

Usage¶

ts2po [options] <ts> <po>
po2ts [options] <po> <ts>

Where:

Options (ts2po):

Options (po2ts):

Examples¶

ts2po -P psi.ts psi.pot

This will create a POT file called psi.pot from the Qt .ts file called psi.ts.

po2ts af.po psi_af.ts

Now take your translated PO files af.po and convert it into a translated Qt .ts file, psi_af.ts.

NOTE:

Bugs¶

There are probably still some bugs related to migrating the various attributes across for the different formats. The converters don’t support all the newer features of the TS format, whereas the native support of Virtaal and Pootle is much better.

txt2po¶

txt2po allows you to use the same principles of PO files with normal text files. In PO only items that change are marked fuzzy and only new items need to be translated, unchanged items remain unchanged for the translation.

Usage¶

txt2po [options] <foo.txt> <foo.po>
po2txt [options] [-t <foo.txt>] <XX.po> <foo-XX.txt>

Where:

Options (txt2po):

Options (po2txt):

A roundtrip example¶

Preparing input files¶

With txt2po a text file is broken down into sections. Each section is separated by a line of whitespace. Each section will appear as a msgid in the PO file. Because of this simple method of breaking up the input file it might be necessary to alter the layout of your input file. For instance you might want to separate a heading from a paragraph by using whitespace.

For steps in a process you would want to leave a blank line between each step so that each step can be translated independently.

For a list of items you might want to group them together so that a translator could for example place them in alphabetic order for their translation.

Once the input file is prepared you can proceed to the next step.

Creating the POT files¶

This is simple:

txt2po -P TEXT_FILE text_file.pot

A translator would copy the POT file to their own PO file and then create translations of the entries. If you wish to create a PO file and not a POT file then leave off the -P option.

You might want to manually edit the POT file to remove items that should not be translated. For instance if part of the document is a license you might want to remove those if you do not want the license translated for legal reasons.

Translating¶

Translate as normal. However translators should be aware that writers of the text file may have used spaces, dashes, equals, underscores and other aids to indicate things such as:

* Headings and sub-headings
* Code examples, command lines examples
* Various lists
* etc

They will need to adapt these to work in their language being aware of how they will appear once they are merged with the original text document.

Creating a translated text file¶

With the translations complete you can create a translated text file like this:

po2txt -w 75 -t TEXT_FILE translated.po TEXT_FILE.translated

This uses the original text file as a template and creates a new translated text file using the translations found in the PO file.

The -w command allows you to reflow the translated text to N number of characters, otherwise the text will appear as one long line.

Help with Wiki syntax¶

dokuwiki¶

To retrieve the raw syntax for your dokuwiki page add ‘?do=export_raw’ to you URL. The following would retrieve the DokuWiki home page in raw dokuwiki format https://www.dokuwiki.org/dokuwiki?do=export_raw

wget https://www.dokuwiki.org/dokuwiki?do=export_raw -O txt2po.txt
txt2po --flavour=dokuwiki -P txt2po.txt txt2po.pot
# edit txt2po.pot
po2txt -t txt2po.txt fr.po fr.txt

First we retrieve the file in raw dokuwiki format, then we create a POT file for editing. We created a French translation and using po2txt plus the original file as a template we output fr.txt which is a French version of the original txt2po.txt. This file can now be uploaded to the wiki server.

MediaWiki¶

To retrieve the raw media wiki syntax add ‘?action=raw’ to you wiki URL. The following retrieves the Translate Toolkit page from Wikipedia in raw MediaWiki format Translate_Toolkit?action=raw.

To process follow the instructions above but substituting the MediaWiki retrieval method.

web2py2po¶

Converts web2py translation files to PO files and vice versa.

Web2py, formerly known as Gluon) is an open-source, Python-based web application framework by Massimo Di Pierro (inspired by Django and Rails).

Web2py uses an internal localization engine based on Python dictionaries, which is applied with the T() lookup function. Web2py provides a built-in translation interface for the T()-engine, which is excellent for rapid application development.

On the other hand, for collaboration and workflow control in a wider community you might probably rather want to use Pootle, Launchpad or similar facilities for translation, thus need to transform the web2py dictionaries into PO files and vice versa. And exactly that is what the web2py2po converters are good for.

Usage¶

web2py2po [options] <web2py> <po>
po2web2py [options] <po> <web2py>

Where:

Options (web2py2po):

Options (po2web2py):

Notes¶

Handling of blanks/untranslated messages:

Untranslated messages in the web2py translation files are usually marked with a leading %%"*** "%%, so:

xliff2po¶

Converts XLIFF localization files to Gettext PO files. XLIFF is the XML Localization Interchange File Format developed by OASIS (Organization for the Advancement of Structured Information Standards) to allow translation work to be standardised no matter what the source format and to allow the work to be freely moved from tool to tool.

Usage¶

po2xliff [options] <po> <xliff>
xliff2po [options] <xliff> <po>

Where:

Options (xliff2po):

Options (po2xliff):

Examples¶

xliff2po -P xliff pot

Create POT files from the XLIFF files found in directory xliff and output them to the directory pot

po2xliff xh xh-xlf

Convert the Xhosa PO files in xh to XLIFF and place them in xh-xlf

Bugs¶

This filter is not yet extensively used… expect bugs. See XLIFF to see how well our implementation conforms to the standard.

The PO plural implementation is still very new and needs active testing.

yaml2po¶

New in version 2.2.6.

Converts YAML localization files to Gettext PO format.

Usage¶

yaml2po [options] <yml> <po>
po2yaml [options] <po> <yml>

Where:

Options (yaml2po):

Options (po2yaml):

Formats Supported¶

Check YAML format document to see to which extent the YAML format is supported.

Examples¶

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

First we need to create a set of POT files:

yaml2po -P lang/en pot/

All .yml files found in the lang/en directory are converted to Gettext POT files 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:

yaml2po -t lang/en lang/zu po-zu/

Using the English YAML files found in lang/en and your existing Zulu translation in lang/zu we create a set of PO files in po-zu. These will now have your translations. Please be aware that in order for that to work 100% you need to have both English and Zulu 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:

po2yaml -t lang/en po-zu/ lang/zu

Your translations found in the Zulu PO directory, po-zu, will be converted to YAML using the files in lang/en as templates and placing your new translations in lang/zu.

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

–accelerator=ACCELERATOR¶

–duplicates=DUPLICATESTYLE¶

Gettext PO files only allow one message with a common msgid (source string). Many other formats allow duplicate entries. To create a valid PO file you need to merge these duplicate entries into one PO message. However, this often negatively affects the roundtrip or is not what is expected by the user. Thus we have a number of methods of handling duplicates which we call duplicate styles.

Also affected are conversions in which the source format is empty (allowing possible translation). As the header in a PO file is identified by an empty source string, your message will appear to be a duplicate of the header. In this case duplicate removal is critical.

Previously the tools used msgid_comment (KDE style comments) to disambiguate text. However, with the release of Gettext 0.15, the new msgctxt disambiguation is now recommended, especially if you wish to use your files with other Gettext the tools. Many other pieces of software now also support this feature, and will probably become the best choice for almost all circumstances. It is the default in our converters.

merge¶

This is the traditional Gettext approach. All messages with the same source string or English string are merged into one PO message.

#: file1.dtd:instruction_manual
#: file1.dtd:manual_process
msgid "Manual"
msgstr ""

If however the source text is blank (these are often configuration options in Mozilla) then the merge style will use KDE comments as used in the msgid_comment style in order to create unambiguous entries that can still be used for configuration.

#: file1.dtd:translators_name
msgid "_: file1.dtd:translators_name\n"
msgstr ""
#: file1.dtd:translators_email
msgid "_: file1.dtd:translators_email\n"
msgstr ""

msgctxt (default)¶

This uses the msgctxt feature of Gettext that was introduced with Gettext 0.15. Some tools might not support it 100%. This option is the default in recent releases of the Translate Toolkit.

#: file1.dtd:instruction_manual
msgctxt "instruction_manual"
msgid "Manual"
msgstr ""
#: file1.dtd:manual_process
msgctxt "manual_process"
msgid "Manual"
msgstr ""

–errorlevel=ERRORLEVEL¶

This is a parameter that can be passed to most of the programs in the translate toolkit in order to choose the level of feedback that you need when errors occur. It is mostly useful for debugging. Please report your errors to the developers with --errorlevel=traceback.

none¶

Display no error messages

message¶

Display on the error message

An error occurred processing PO file

exception¶

Give the error message and name and Python exception

ValueError: An error occurred processing PO file

traceback¶

Provide a full traceback for debugging purposes

csv2po: warning: Error processing: nso/readlicense_oo/docs/readme.csv: Traceback (most recent call last):


  File "/usr/lib/python2.4/site-packages/translate/misc/optrecurse.py", line 415, in recursiveprocess


    success = self.processfile(fileprocessor, options, fullinputpath, fulloutputpath, fulltemplatepath)


  File "/usr/lib/python2.4/site-packages/translate/misc/optrecurse.py", line 468, in processfile


    if fileprocessor(inputfile, outputfile, templatefile, **passthroughoptions):


  File "/usr/lib/python2.4/site-packages/translate/convert/csv2po.py", line 183, in convertcsv


    outputpo = convertor.convertfile(inputcsv)


  File "/usr/lib/python2.4/site-packages/translate/convert/csv2po.py", line 159, in convertfile


    raise ValueError("An error occurred processing PO file")
ValueError: An error occurred processing PO file

–filteraction=ACTION¶

none (default)¶

Take no action. Messages from failing test will appear in the output file

warn¶

Print a warning but otherwise include the message in the output file.

exclude-serious¶

Only exclude errors that are listed as serious by the convertor. All other are included.

exclude-all¶

Exclude any message that fails a test.

–multifile=MULTIFILESTYLE¶

This options determines how the POT/PO files are split from the source files. In many cases you have source files that generate either too many small files or one large files which you would rather see split up into smaller files.

single¶

Output individual files.

toplevel¶

Split the source files at the top level. I.e., you see a number of top level files.

onefile¶

One large file instead of many smaller files.

–personality=TYPE¶

java (default)¶

Create output strictly according to the specification for .properties files. This will use escaped Unicode for any non-ASCII characters. Thus the following string found in a PO file:

ṽḁḽṻḝ

Will appear as follows in the output .properties file:

\u1E7D\u1E01\u1E3D\u1E7B\u1E1D

mozilla¶

Mozilla has made slight adjustments to the Java .properties spec. Mozilla will accept UTF-8 encoded strings in the property file and thus does not need escaped Unicode. Thus the above string – ṽḁḽṻḝ – will not be escaped. Mozilla property files are thus more useful for non-Latin languages in that they are actually readable.

Of course this style of file is only used by Mozilla and should not be used for other projects that follow the Java spec more strictly.

skype¶

Skype .lang files are .properties files in UTF-16. The & is used as an accelerator (marked in the PO header).

flex¶

Flex follows the Mozilla approach, a UTF-8 encoded file with no escaped unicode. We include it as its own dialect for ease of use.

strings¶

Much Mac OS X and iPhone software is translated using .strings files. These are quite different from properties files and we treat them here as key value files.

The files are in UTF-16 with a few minor escaping conventions.

–progress=PROGRESS¶

All of the programs can give visual feedback. This options allows you to select the style of that feedback.

In the examples we are converting and OpenOffice.org 2.0 sdf/gsi file into POT files using oo2po.

none¶

No visual feedback, this is useful if you want to use any of the scripts as part of another script and don’t want feedback to interfere with the operation.

$ oo2po -P --progress=none en-US.sdf pot
$

dots¶

Use visual dots to represent progress. Each dot represent a file that has been processed.

$ oo2po -P --progress=dots en-US.sdf pot
.............................................................................................
.............................................................................................
.........................................
$

bar (default)¶

Use a progress bar consisting of hashes (#) to show progress.

$ oo2po -P --progress=bar en-US.sdf pot
processing 227 files...
[##############################             ]  69%

This is the default mode of operation, therefore this command would create the same output.

$ oo2po -P en-US.sdf pot

verbose¶

Combine the hash (#) progress bar form the bar option with the actual names of files that have been processed.

$ oo2po -P --progress=verbose en-US.sdf pot
processing 227 files...
so3/src.oo
dbaccess/source/ui/uno.oo
helpcontent2/source/text/shared.oo
wizards/source/formwizard.oo
sch/source/ui/dlg.oo
helpcontent2/source/text/sbasic/shared/01.oo
dbaccess/source/core/resource.oo
svtools/source/sbx.oo
dbaccess/source/ui/relationdesign.oo
scp2/source/writer.oo
filter/source/xsltdialog.oo
[##                                         ]   5%

names¶

Prints out only the filenames without any other progress indicator. This is a good option when outputting to a log file rather than a terminal.

$ oo2po -P --progress=names en-US.sdf pot
so3/src.oo
dbaccess/source/ui/uno.oo
helpcontent2/source/text/shared.oo
wizards/source/formwizard.oo
sch/source/ui/dlg.oo
helpcontent2/source/text/sbasic/shared/01.oo
dbaccess/source/core/resource.oo
svtools/source/sbx.oo
dbaccess/source/ui/relationdesign.oo
scp2/source/writer.oo
filter/source/xsltdialog.oo

Converters change many different formats to PO and back again. Sometimes only one direction is supported, or conversion is done using non-PO formats. The converters follow a general pattern of usage, understanding that will make the converters much easier to use and understand.

Tools¶

The PO tools allow you to manipulate and work with PO files

Quality Assurance¶

junitmsgfmt¶

New in version 3.9.

Added –untranslated flag, to enable reporting of untranslated messages.

New in version 1.7.

Run msgfmt and provide JUnit type output for use in continuous integration systems like Hudson and Jenkins.

Usage¶

junitmsgfmt po/*.po > msgfmt_junit.xml

poconflicts¶

poconflicts takes a PO file and creates an set of output PO files that contain messages that conflict. During any translation project that involves a large amount of work or a number of translators you will see message conflicts. A conflict is where the same English message has been translated differently (in some languages this may have been intentional). Conflicts occur due to different translation style or a shift in translations as the translators or project mature.

poconflicts allows you to quickly identify these problem messages, investigate and correct them. To merge the files back, they have to be restructured into the correct directory structure using porestructure in order to enable merging using pomerge.

Usage¶

poconflicts [options] <po> <conflicts>

Where:

Options:

Examples¶

Here are some examples that demonstrate the usefulness of poconflict

poconflicts --accelerator=~ -I xhosa conflicts

This extracts messages from the PO files in the xhosa directory and places a new PO file for each identified conflict in conflicts. We are working with OpenOffice files and we therefore use the tilde (~) as the accelerator marker (with this set F~ile is considered the same as ~File). We are also ignoring the case of the message using -I (thus File is considered the same as file or FILE)

Another useful option is to look at the inverted conflicts. This will detect target words that have been used to translate different source words.

poconflicts --accelerator=~ -I -v xhosa conflicts

Now in the conflicts directory we will find PO files based on the Xhosa word. We can now check where a Xhosa word has been used for different source or English words. Often there is no problem but you might find cases where the same Xhosa word was used for Delete and Cancel – clearly a usability issue.

The translator makes the needed corrections to the files and then we can proceed to merge the results back into the PO files. Unchanged entries can be removed.

Now restructure the files to resemble the original directory structure using porestructure:

porestructure -i conflicts -o conflicts_tree

Now merge the changes back using pomerge:

pomerge -t xhosa -i conflicts_tree -o xhosa

This takes the corrected files from conflicts_tree and merge them into the files in xhosa using the same files as templates.

pofilter¶

Pofilter allows you to run a number of checks against your PO, XLIFF or TMX files. These checks are designed to pick up problems with capitalisation, accelerators, variables, etc. Those messages that fail any of the checks are output and marked so that you can correct them.

Use pofilter -l to get a list of available checks.

Once you have corrected the errors in your PO files you can merge the corrections into your existing translated PO files using pomerge.

Usage¶

pofilter [options] <in> <out>

Where:

Options: