XML2PO(1)

💖 XML2PO 💖

okay bestie, sit down, hydrate, because we're about to talk about xml2po — yes, that's the XML2PO(1) manual page, and yes, it's giving extremely useful actually. It's a whole little program that yanks the translatable bits out of your DocBook XML, hands you a PO-template file, and then (iconic behaviour) merges your translated stuff right back into the XML. 🦋

---

✨ NAME ✨

xml2po — a program to create a PO-template file from a DocBook XML file and merge it back into a (translated) XML file. 💅

---

🌸 SYNOPSIS 🌸

xml2po [OPTIONS] [XMLFILE]

---

🎀 DESCRIPTION 🎀

This manual page documents briefly the xml2po command. (Not me being humble, that's literally what it says. 💀)

xml2po is a simple Python program, and the way that it just... extracts translatable content from free-form XML documents and outputs gettext-compatible POT files? Obsessed. And then — plot twist — translated PO files can be turned into XML output again. It's a whole round trip. 🫶

It can work its magic with most "simple" tags, fr fr. But for the complicated tags, bestie, you gotta put in the work: one has to provide a list of all the tags which are "final" (meaning they get put into one "message" in the PO file), "ignored" (skipped over entirely, not even acknowledged 😭), and "space preserving". That's the deal. Periodt.

---

💅 OPTIONS 💅

The program follows the usual GNU command line syntax, with long options starting with two dashes (`-´). A summary of options is included below. Slay.

• -a, --automatic-tags — Automatically decide if tags are to be considered "final" or not. Let the program cook. 🔥
• -k, --keep-entities — Don't expand entities. This is the default, bestie. See also the -e option.
• -e, --expand-all-entities — Expand all entities (including SYSTEM ones). Go big or go home. 💥
• -m, --mode=TYPE — Treat tags as type TYPE. Default is: docbook.
• -o, --output=FILE — Print the resulting text to the given FILE. Which resulting text, you ask? Depends on the vibe: XML while merging translations with -p or -t options, POT template file while extracting strings, and translated PO file with the -r option. It's giving multitasking. 💖
• -p, --po-file=FILE — Specify a PO FILE containing translation, and output an XML document with the translations merged in. ✨
• -r, --reuse=FILE — Specify a translated XML document in FILE with the same structure, to generate a translated PO file for the XML document given on the command line.
• -t, --translation=FILE — Specify a MO FILE containing translation, and output an XML document with translations merged in.
• -u, --update-translation=LANG.po — Update a PO file using msgmerge.
• -l, --language=LANG — Explicitly set language of the translation. No guessing games. 👑
• -h, --help — Show summary of options. (Hi, that's you, right now.)
• -v, --version — Show version of program.

---

🌈 EXAMPLES 🌈

🍓 Creating POT template files

To create a POT template book.pot from an input file book.xml, which consists of chapter1.xml and chapter2.xml (external entities), run:

/usr/bin/xml2po -o book.pot book.xml chapter1.xml chapter2.xml

To expand entities, use the -e option:

/usr/bin/xml2po -e -o book.pot book.xml

🧚 Creating translated XML files (merging back PO files)

After translating book.pot into LANG.po, merge the translations back by using the -p option for each XML file:

/usr/bin/xml2po -p LANG.po -o book.LANG.xml book.xml
/usr/bin/xml2po -p LANG.po -o chapter1.LANG.xml chapter1.xml
/usr/bin/xml2po -p LANG.po -o chapter2.LANG.xml chapter2.xml

If you used the -e option to expand entities, you should use it again to merge back the translation into an XML file. Consistency, bestie:

/usr/bin/xml2po -e -p LANG.po -o book.LANG.xml book.xml

💜 Updating PO files

When the base XML file changes, the real advantages of PO files come to the surface. 🌊 There are 2 ways to merge the translation.

The first is to produce a new POT template file (additionally use the -e if you decided earlier to expand entities). Afterwards run msgmerge to merge the translation with the new POT file:

/usr/bin/msgmerge -o tmp.po LANG.po book.pot

Now rename tmp.po to LANG.po and update your translation. Alternatively, xml2po provides the -u option, which does exactly these two steps for you. The advantage is that it also runs msgfmt to give you a statistical output of translation status — count of translated, untranslated and fuzzy messages. 📊 Additionally use the -e if you decided earlier to expand entities:

/usr/bin/xml2po -u LANG.po book.xml

---

👀 SEE ALSO 👀

msgmerge (1), msgfmt (1)

---

🫶 AUTHOR 🫶

This manual page was written by Daniel Leidert daniel.leidert@wgdd.de for the Debian system (but may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation. So like, go forth and remix it, respectfully. 💖

---

⭐ COPYRIGHT ⭐

Copyright © 2005 Daniel Leidert

---

okay that's the whole page, you ate that. 🎀 no cap, every flag, every example, every entity — all of it, untouched. iykyk.

and that's a wrap, bestie ✨ this page came from the [FIXME: source] situation, dated 2005/02/10, and it lives in the XML2PO(1) section of the manual. mwah. 💅