Contents
po4a (PO for anything) eases documentation translation maintenance using the classical gettext tools. The main feature of po4a is that it decouples the translation of content from its document.
Free Software philosophy is to make technology truly available to everyone and localization is a key factor. Untranslated free software is useless for non-English speakers. Therefore, we still have some work to do to make software available to everybody.
Especially in case of technical documentation, it is essential that translations are updated timely too.
This page describes the po4a workflow, some Debian packages for automating translation and spellcheck are mentioned in the L10N project
po4a current supported formats
po4a supported formats are:
- TeX / LaTeX
- man
AsciiDoc
- pod
- sgml
- text
- xml and XHMTL
- texinfo
General workflow
Workflow for any format usually is:
- Convert from original format to .po
- Translate, review and validate .po
- Convert back to the original format from .po
LaTeX Translation Workflow
Workflow for LaTeX documents, including noweb documents:
.nw (optional) -> .tex -> .pot -> .po -> translate -> .tex
.nw -> .tex
Converting .nw file into .tex.
This step is only needed in case of noweb documents. noweb documents are suffixed with .nw
noweave -index -delay <file name>.nw > <file name>.tex
.tex -> .pot
Converting .tex file into .pot.
.pot files are templates for language specific .po files.
po4a-gettextize --format latex --master-charset utf8 \ --copyright-holder "<name>" \ --package-name "<package name>" --package-version "<version>" \ --master <file name>.tex --po <file name>.pot
.pot -> .po
For each language is required to create a translation file. A .po file is created per language. gettext need to be installed for these actions.
When creating a .po, msginit, to update an existing .po with new strings in a .pot file, msgmerge.
Files to be translated are .po ones.
creating a .po from .pot
msginit --input=<file name>.pot \ --output-file=<file name>.po \ --locale=<ISO code for language> --no-translator
Updating a .po from .pot
msgmerge --verbose --update <file name>.po <file name>.pot
Translation work
.po files are the one to be translated. Debian packages various tools to ease .po files management. gtranslator, (GNOME Translation Editor) is a po file editor which makes translating gettext applications as easy as possible, even with no translation experience.
.po -> .tex
Converting .po file into .tex.
po4a-translate --format latex --master-charset utf8 \ --master <path>/<file name>.tex \ --localized <path>/<file name>.tex \ --po <po-Datei>.po --keep 30
Where keep stands for minimal threshold percentage translation to keep (i.e. write), in this case is set to 30 (default is 80). I.e. by default, files have to be translated at least at 80% to get written.
Outputting other formats from LaTeX
Generate a pdf
texlive-latex-base pdflatex converts LaTeX to PDF |
pdflatex <file name>.tex
Bibliographies can be created with bibtex.
Generate e-books
epub format
texlive-extra-utils includes tex4ebook conversion tool from LaTeX to epub. |
tex4ebook -f epub <file name>.tex <directory for the e-book>
mobi format
calibre offers support to generate .mobi ebook formatted. |
shell scrtipt to generate e-book from noweb.
Sample of po4a usage to translate dia diagrams
This is a Howto by example to describe using po4a with dia sketch.
i18n/l10n of a dia sketch
=========================
1. Source file: network-arch3.dia (special XML vector graphic)
2. Init translation/Create pot file by means of po4a:
$ po4a-gettextize -f dia -m network-arch3.dia -p network-arch3.pot
3. Edit pot file: I removed strings that should not be translated.
I reordered strings as they are seen in the sketch.
---------------------- :: Repeate and Fade :: -------------------------
4. Create a po file for each locale (e.g. German=de):
$ msginit --locale=de --input=network-arch3.pot
--> creates de.po
5. Edit/Translate the po file.
6. Translate the source file as follows (-k 10 to make it work with few translations):
$ po4a-translate -k 10 -f dia -m network-arch3.dia -p de.po -l network-arch3-de.dia
7. Export from dia to more common file formats:
$ dia-normal -n -t svg network-arch3-de.dia
--> creates svg vector file
$ convert network-arch3-de.svg -resize 50% network-arch3-de.png
--> creates a bitmap image of apt size, here.
----------------------------- :: Coda :: ----------------------------------
Don't forget to convert your source file like (7):
$ dia-normal -n -t svg network-arch3.dia
$ convert network-arch3.svg -resize 50% network-arch3.png