.. _pot2po:

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:: This tool also works with translation formats other than Gettext PO,
   for example ``XLIFF``.


.. _pot2po#usage:

Usage
=====

::

  pot2po [options] <pot> <po>

Where:

+--------+---------------------------------------------------------+
| <pot>  | is a PO Template (POT) file or directory of POT files   |
+--------+---------------------------------------------------------+
| <po>   | is a PO file or a directory of PO files                 |
+--------+---------------------------------------------------------+

Options:

--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: :doc:`dots, none, bar, names, verbose <option_progress>`
--errorlevel=ERRORLEVEL
                      show errorlevel as: :doc:`none, message, exception,
                      traceback <option_errorlevel>`
-i INPUT, --input=INPUT   read from INPUT in catkeys, lang, pot, ts, xlf, xliff
                        formats
-x EXCLUDE, --exclude=EXCLUDE  exclude names matching EXCLUDE from input paths
-o OUTPUT, --output=OUTPUT     write to OUTPUT in catkeys, lang, po, pot, ts, xlf,
                        xliff formats
-t TEMPLATE, --template=TEMPLATE   read from TEMPLATE in catkeys, lang, po, pot, ts, xlf,
                        xliff formats (old translations)
-S, --timestamp      skip conversion if the output file has newer timestamp
-P, --pot            output PO Templates (.pot) rather than PO files (.po)
--tm=TM              The file to use as translation memory when fuzzy matching
-s MIN_SIMILARITY, --similarity=MIN_SIMILARITY   The minimum similarity for inclusion (default: 75%)
--nofuzzymatching    Disable all fuzzy matching


.. _pot2po#examples:

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.

:command:`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
:doc:`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%*.


.. _pot2po#merging:

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:

* If everything matches we carry that across
* We can resurrect obsolete messages for reuse
* Messages no longer used are made obsolete
* If we cannot find a match we will first look through the current and obsolete
  messages and then through any global translation memory
* Fuzzy matching makes use of the :doc:`/commands/levenshtein_distance`
  algorithm to detect the best matches


.. _pot2po#performance:

Performance
===========

Fuzzy matches are usually of good quality. Installation of the
`python-Levenshtein <https://pypi.python.org/pypi/python-Levenshtein>`_ package
will speed up fuzzy matching. Without this a Python based matcher is used which
is considerably slower.


.. _pot2po#bugs:

Bugs
====

* :doc:`pomerge` and pot2po should probably become one.