~ubuntu-branches/ubuntu/lucid/gnome-doc-utils/lucid

.\"Generated by db2man.xsl. Don't modify this, modify the source.

.de Sh \" Subsection

.br

.if t .Sp

.ne 5

.PP

\fB\\$1\fR

.PP

..

.de Sp \" Vertical space (when we can't use .PP)

.if t .sp .5v

.if n .sp

..

.de Ip \" List item

.br

.ie \\n(.$>=3 .ne \\$3

.el .ne 3

.IP "\\$1" \\$2

..

.TH "XML2PO" 1 "2005/02/10" "" ""

.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"

.ad l

.hy 0

.HP 7

\fBxml2po\fR [\fBOPTIONS\fR] [\fIXMLFILE\fR]

.ad

.hy

 

.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\&.

 

.TP

\fB\-a\fR, \fB\-\-automatic\-tags\fR

Automatically decides if tags are to be considered "final" or not\&.

 

.TP

\fB\-k\fR, \fB\-\-keep\-entities\fR

Don't expand entities (default)\&. See also the \fB\-e\fR option\&.

 

.TP

\fB\-e\fR, \fB\-\-expand\-all\-entities\fR

Expand all entities (including SYSTEM ones)\&.

 

.TP

\fB\-m\fR, \fB\-\-mode=\fITYPE\fR\fR

Treat tags as type \fITYPE\fR (default: docbook)\&.

 

.TP

\fB\-o\fR, \fB\-\-output=\fIFILE\fR\fR

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\&.

 

.TP

\fB\-p\fR, \fB\-\-po\-file=\fIFILE\fR\fR

Specify a PO FILE containing translation and output XML document with translations merged in\&. Using this option will overwrite the temporary file \fI\&.xml2po\&.mo\fR\&.

 

.TP

\fB\-r\fR, \fB\-\-reuse=\fIFILE\fR\fR

Specify a translated XML document in FILE with the same structure to generate translated PO file for XML document given on command line\&.

 

.TP

\fB\-t\fR, \fB\-\-translation=\fIFILE\fR\fR

Specify a MO file containing translation and output XML document with translations merged in\&.

 

.TP

\fB\-u\fR, \fB\-\-update\-translation=\fILANG\&.po\fR\fR

Updates a PO file using \fBmsgmerge\fR\&.

 

.TP

\fB\-l\fR, \fB\-\-language=\fILANG\fR\fR

Explicitely set language of the translation\&.

 

.TP

\fB\-h\fR, \fB\-\-help\fR

Show summary of options\&.

 

.TP

\fB\-v\fR, \fB\-\-version\fR

Show version of program\&.

 

.SH "EXAMPLES"

 

.SS "Creating POT template files"

 

.PP

To create a POT template \fIbook\&.pot\fR from an input file \fIbook\&.xml\fR, which consists of \fIchapter1\&.xml\fR and \fIchapter2\&.xml\fR (external entities), run:

 

.nf

 

                                \fB/usr/bin/xml2po\fR \fB\-o\fR book\&.pot book\&.xml chapter1\&.xml chapter2\&.xml

                        

.fi

 

.PP

To expand entities use the \fB\-e\fR option:

 

.nf

 

                                \fB/usr/bin/xml2po\fR \fB\-e \-o\fR book\&.pot book\&.xml

                        

.fi

 

.SS "Creating translated XML files (merging back PO files)"

 

.PP

After translating \fIbook\&.pot\fR into \fILANG\&.po\fR, merge the translations back by using \fB\-p\fR option for each XML file:

 

.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

 

.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:

 

.nf

 

                                \fB/usr/bin/xml2po\fR \fB\-e \-p\fR LANG\&.po \fB\-o\fR book\&.LANG\&.xml book\&.xml

                        

.fi

 

.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:

 

.nf

 

                                \fB/usr/bin/msgmerge\fR \fB\-o\fR tmp\&.po LANG\&.po book\&.pot

                        

.fi

 

.PP

Now rename \fItmp\&.po\fR to \fILANG\&.po\fR 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:

 

.nf

 

                                \fB/usr/bin/xml2po\fR \fB\-u\fR LANG\&.po book\&.xml

                        

.fi

 

.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\&.