'\" t
.\"     Title: XML2PO
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 2005/02/10
.\"    Manual: [FIXME: manual]
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "XML2PO" "1" "2005/02/10" "[FIXME: source]" "[FIXME: manual]"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
xml2po \- program to create a PO\-template file from a DocBook XML file and merge it back into a (translated) XML file
.SH "SYNOPSIS"
.HP \w'\fBxml2po\fR\ 'u
\fBxml2po\fR [\fBOPTIONS\fR] [\fIXMLFILE\fR]
.SH "DESCRIPTION"
.PP
This manual page documents briefly the
\fBxml2po\fR
command\&.
.PP

\fBxml2po\fR
is a simple Python program which extracts translatable content from free\-form XML documents and outputs gettext compatible POT files\&. Translated PO files can be turned into XML output again\&.
.PP
It can work it\'s magic with most "simple" tags, and for complicated tags one has to provide a list of all tags which are "final" (that will be put into one "message" in PO file), "ignored" (skipped over) and "space preserving"\&.
.SH "OPTIONS"
.PP
The program follows the usual GNU command line syntax, with long options starting with two dashes (`\-\')\&. A summary of options is included below\&.
.PP
\fB\-a\fR, \fB\-\-automatic\-tags\fR
.RS 4
Automatically decide if tags are to be considered "final" or not\&.
.RE
.PP
\fB\-k\fR, \fB\-\-keep\-entities\fR
.RS 4
Don\'t expand entities (default)\&. See also the
\fB\-e\fR
option\&.
.RE
.PP
\fB\-e\fR, \fB\-\-expand\-all\-entities\fR
.RS 4
Expand all entities (including SYSTEM ones)\&.
.RE
.PP
\fB\-m\fR, \fB\-\-mode=\fR\fB\fITYPE\fR\fR
.RS 4
Treat tags as type
\fITYPE\fR
(default: docbook)\&.
.RE
.PP
\fB\-o\fR, \fB\-\-output=\fR\fB\fIFILE\fR\fR
.RS 4
Print resulting text (XML while merging translations with "\-p" or "\-t" options, POT template file while extracting strings, and translated PO file with "\-r" option) to the given FILE\&.
.RE
.PP
\fB\-p\fR, \fB\-\-po\-file=\fR\fB\fIFILE\fR\fR
.RS 4
Specify a PO FILE containing translation and output XML document with translations merged in\&.
.RE
.PP
\fB\-r\fR, \fB\-\-reuse=\fR\fB\fIFILE\fR\fR
.RS 4
Specify a translated XML document in FILE with the same structure to generate translated PO file for XML document given on command line\&.
.RE
.PP
\fB\-t\fR, \fB\-\-translation=\fR\fB\fIFILE\fR\fR
.RS 4
Specify a MO file containing translation and output XML document with translations merged in\&.
.RE
.PP
\fB\-u\fR, \fB\-\-update\-translation=\fR\fB\fILANG\&.po\fR\fR
.RS 4
Update a PO file using
\fBmsgmerge\fR\&.
.RE
.PP
\fB\-l\fR, \fB\-\-language=\fR\fB\fILANG\fR\fR
.RS 4
Explicitly set language of the translation\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Show summary of options\&.
.RE
.PP
\fB\-v\fR, \fB\-\-version\fR
.RS 4
Show version of program\&.
.RE
.SH "EXAMPLES"
.SS "Creating POT template files"
.PP
To create a POT template
book\&.pot
from an input file
book\&.xml, which consists of
chapter1\&.xml
and
chapter2\&.xml
(external entities), run:
.sp
.if n \{\
.RS 4
.\}
.nf
				\fB/usr/bin/xml2po\fR \fB\-o\fR book\&.pot book\&.xml chapter1\&.xml chapter2\&.xml
			
.fi
.if n \{\
.RE
.\}
.PP
To expand entities use the
\fB\-e\fR
option:
.sp
.if n \{\
.RS 4
.\}
.nf
				\fB/usr/bin/xml2po\fR \fB\-e \-o\fR book\&.pot book\&.xml
			
.fi
.if n \{\
.RE
.\}
.SS "Creating translated XML files (merging back PO files)"
.PP
After translating
book\&.pot
into
LANG\&.po, merge the translations back by using
\fB\-p\fR
option for each XML file:
.sp
.if n \{\
.RS 4
.\}
.nf
				\fB/usr/bin/xml2po\fR \fB\-p\fR LANG\&.po \fB\-o\fR book\&.LANG\&.xml book\&.xml
				\fB/usr/bin/xml2po\fR \fB\-p\fR LANG\&.po \fB\-o\fR chapter1\&.LANG\&.xml chapter1\&.xml
				\fB/usr/bin/xml2po\fR \fB\-p\fR LANG\&.po \fB\-o\fR chapter2\&.LANG\&.xml chapter2\&.xml
			
.fi
.if n \{\
.RE
.\}
.PP
If you used the
\fB\-e\fR
option to expand entities, you should use it again to merge back the translation into an XML file:
.sp
.if n \{\
.RS 4
.\}
.nf
				\fB/usr/bin/xml2po\fR \fB\-e \-p\fR LANG\&.po \fB\-o\fR book\&.LANG\&.xml book\&.xml
			
.fi
.if n \{\
.RE
.\}
.SS "Updating PO files"
.PP
When base XML file changes, the real advantages of PO files come to surface\&. There are 2 ways to merge the translation\&. The first is to produce a new POT template file (additionally use the
\fB\-e\fR
if you decided earlier to expand entities)\&. Afterwards run
\fBmsgmerge\fR
to merge the translation with the new POT file:
.sp
.if n \{\
.RS 4
.\}
.nf
				\fB/usr/bin/msgmerge\fR \fB\-o\fR tmp\&.po LANG\&.po book\&.pot
			
.fi
.if n \{\
.RE
.\}
.PP
Now rename
tmp\&.po
to
LANG\&.po
and update your translation\&. Alternatively,
\fBxml2po\fR
provides the
\fB\-u\fR
option, which does exactly these two steps for you\&. The advantage is, that it also runs
\fBmsgfmt\fR
to give you a statistical output of translation status (count of translated, untranslated and fuzzy messages)\&. Additionally use the
\fB\-e\fR
if you decided earlier to expand entities:
.sp
.if n \{\
.RS 4
.\}
.nf
				\fB/usr/bin/xml2po\fR \fB\-u\fR LANG\&.po book\&.xml
			
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP

\fBmsgmerge\fR
(1),
\fBmsgfmt\fR
(1)
.SH "AUTHOR"
.PP
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\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2005 Daniel Leidert
.br