po-debiandoc - ease translating DebianDoc SGML documents

debiandoc2pot original-SGML

debiandoc-gettextize [-k] [-r] original-SGML translated-SGML

po2debiandoc [-P FILE] [-m MODE] [-s COMMAND] [-W NUMBER] original-SGML PO-file

This manual page describes some tools provided to help translators of Debiandoc SGML documents. A basic knowledge of l10n (`localization') with gettext is assumed, read its documentation for an introduction.

These tools are derived from those written by the KDE Team, shipped in the poxml package on Debian GNU/Linux. The main idea is to create a PO file from two structurally identical SGML files, original and its translation. When a new original document is published, a new POT is created and PO file is updated. Then translated document is generated with the same SGML structure as in original, but in which strings are replaced by the ones found in PO file.

-h, --help

Display a usage summary for each program and exit

-v, --verbose

Process in verbose mode

-f, --fragment=BILEVEL

Input file is a fragment file, it only consists of chapters or appendixes. Argument is either CWchapter or CWappendix.

-k, --keep

Do not delete temporary files after processing

-r, --no-marked-section-delimiters

Remove from input files all marked-section begin (CW<![...[) and end (CW]]>) strings. This may be useful to check translation accuracy, but CWpo2debiandoc must not be called with the generated PO file, because all markers have been removed.

-P, --prolog=BIFILE

Replace original prolog by the one found in FILE.

-W, --width=BINUMBER

Wrap lines to NUMBER columns, and reformat paragraphs to make them easier to read. It is set by default to 80, and formatting is disabled if set to 0.

-m, --message=BIMODE

Choose which messages to display. When MODE is CWuptodate, only up to date translated strings are printed, and outdated strings are replaced by original strings. When MODE is CWfuzzy, translated strings are always displayed, even if they are fuzzy. When MODE is CWoriginal, original strings are printed, this is useful to check that this program do not corrupt files. And when MODE is CWboth, both translated and original strings are printed.

-s, --substitute=BICOMMAND

This option takes Perl commands as argument, which are applied to output before displaying. Translated paragraphs are processed separately.

1. Initial PO file

First step is to create a PO file which will be our start point

   debiandoc-gettextize foo.sgml.old foo.xx.sgml.old > xx.po

The two files CWfoo.sgml.old and CWfoo.xx.sgml.old must be synchronized, otherwise PO file could not be extracted. Remember to edit PO header text in order to allow processing by CWgettext tools, and replace CWPACKAGE VERSION by accurate data.

2. Update original SGML

Retrieve a newer original version, which will be translated.

3. Generate POT file

   debiandoc2pot foo.sgml > foo.pot

This step should be straightforward.

4. Update PO file

   msgmerge xx.po foo.pot -o xx.po-new && mv xx.po-new xx.po

Translate strings in CWxx.po and remove fuzzy strings with your favorite gettext-related tools.

5. Build translated SGML document

   po2debiandoc foo.sgml xx.po > foo.xx.sgml

All commands except CWmsgmerge come from CWpo-debiandoc package, whereas CWmsgmerge is part of CWgettext package.

As SGML syntax is less strict than XML, some SGML documents may cause trouble, and extra care must be taken before processing.

Identical structure

In order to create initial PO file, original and translated document must have a similar structure, i.e. have same elements at the same place. This coherence is checked by section, and CWdebiandoc-gettextize raises a warning when an inconsistency is detected. In most cases, this tells that a paragraph was missing or was not removed in translated document. The whole process may be reliable only when there is no such warnings here.

Optional elements and marked sections

When optional elements and marked sections are mixed, input sometimes become unparseable, because structure depends upon parameter entities whose value is undefined. So everything should be done to help parsing, by not omitting optional elements.

These tools mimic the ones written by the KDE Documentation Team, available in Debian in the CWpoxml package.

Denis Barbier <barbier@debian.org>