po4a-translate

Convert a translated PO file back to a document

$ po4a-translate --format [text] --master [path/to/master.doc] --po [path/to/result.po] --localized [path/to/translated.txt]

$ po4a-translate --help-format

po4a-translate [options] input_file po_file output_file

-f, --format <module>
    Specifies the format of the input document. Examples include man, pod, sgml, tex, docbook, or xml. This tells po4a which parsing module to use.

-o, --option <module_options>
    Passes specific options to the chosen translation module. The available options depend on the selected --format.

-M, --master-language <lang>
    Sets the language code of the original (master) document, e.g., en for English.

-L, --localized-language <lang>
    Sets the language code of the translated (localized) document that will be generated, e.g., fr for French.

-k, --keep-non-translated
    If a paragraph or string in the master document is not found translated in the PO file, this option ensures the original (master language) text is retained in the output. Otherwise, such segments might be omitted or marked.

-v, --verbose
    Increases the verbosity level of the output, providing more information about the translation process.

-d, --debug
    Enables debug output, which is useful for troubleshooting issues with the translation process or module parsing.

--no-translator-credits
    Suppresses the addition of standard translator credit lines (often added by default by po4a) to the generated output document.

--poref-encoding <encoding>
    Specifies the character encoding of the input PO file, such as UTF-8.

--src-encoding <encoding>
    Specifies the character encoding of the source (input) document, e.g., ISO-8859-1.

--dest-encoding <encoding>
    Specifies the character encoding of the output (destination) document. This is often the same as the PO file's encoding.

--force
    Forces the translation process to proceed even if minor errors or untranslatable sections are encountered, attempting to produce output regardless.

-h, --help
    Displays a help message with usage information and available options.

-V, --version
    Shows the version information for the po4a-translate command.

po4a-translate is a central utility within the po4a (PO for anything) toolkit. Its primary function is to take a source document (such as a man page, POD file, XML document, or LaTeX file) and a Gettext Portable Object (PO) file containing its translations, and then produce a new document. This new document retains the original format but incorporates the translated content from the PO file. This process is crucial for maintaining multi-lingual documentation, allowing developers and translators to use a standardized workflow based on Gettext. The command supports various document formats through a modular system, parsing and re-assembling the content to ensure translations are accurately placed while preserving the document's structure and layout.

po4a-translate relies heavily on the correctness of the input PO file and the ability of po4a's modules to parse the source document format. Issues can arise if the PO file is malformed, if the source document contains unusual structures not handled by the selected module, or if character encodings are not correctly specified, potentially leading to garbled text or incomplete translations. Non-translated segments will be omitted unless --keep-non-translated is used.

Translating a man page from English to French:

Suppose you have mydoc.en.pod (the original English source document in POD format) and mydoc.fr.po (the French translation PO file). You want to generate mydoc.fr.man (the translated French man page).

The command would be:

po4a-translate -f pod -M en -L fr mydoc.en.pod mydoc.fr.po mydoc.fr.man

This command instructs po4a-translate to use the 'pod' format module, specifying the master language as English and the localized language as French. It then processes the source file, applies the translations from the PO file, and writes the resulting French man page to the specified output file.

The po4a project, including po4a-translate, originated around 2002 within the Debian community with the goal of facilitating the translation of various documentation formats (like man pages and developer documentation) using the well-established Gettext localization framework. This filled a gap where Gettext was primarily used for software string internationalization, but not extensively for documentation. po4a-translate has evolved to support an increasing number of document types and to handle complex document structures, becoming a robust tool for integrating documentation into standard translation workflows.

po4a(7), po4a-gettextize(1), po4a-updatepo(1), msgfmt(1), xgettext(1)