po4a-updatepo

Update a PO file according to the modification of its origin file

$ po4a-updatepo --format [text] --master [path/to/master.txt] --po [path/to/result.po]

$ po4a-updatepo --help-format

$ po4a-updatepo --format [text] --master [path/to/master.txt] --po [path/to/po1.po] --po [path/to/po2.po]

po4a-updatepo [options] config_file

-f, --force
    Force the recreation of internal files, even if they appear up-to-date. This can be useful for troubleshooting.

-v, --verbose
    Increase the verbosity of the output. Multiple '-v' options increase verbosity further.

-d, --debug
    Enable debug output. Useful for developers and advanced troubleshooting.

-q, --quiet
    Suppress all normal output, only showing errors or warnings.

--dry-run
    Perform a trial run without making any actual changes to the PO files or disk. Shows what would happen.

--no-preserve-po
    Do not preserve the original PO file structure during the update process. This might lead to some entries being reordered or formatted differently.

--help
    Display a short help message and exit.

--version
    Display the version information of po4a and exit.

--man
    Display the full manual page for po4a-updatepo.

--shell
    Display a shell script that can be used to run po4a-updatepo, useful for debugging its execution environment.

The po4a-updatepo command is a core utility within the po4a (PO for anything) project. Its primary function is to update translation (PO) files after the original source document from which they were derived has been modified.

When a document undergoes changes, such as adding new paragraphs, modifying existing text, or removing sections, the corresponding PO files need to be synchronized to reflect these alterations. po4a-updatepo automates this process by reading a configuration file that specifies the relationship between source documents and their PO files. It internally leverages po4a-gettextize to extract translatable strings from the updated source and then uses msgmerge to intelligently merge these new strings with the existing translations in the PO file, preserving existing translations where possible and marking new/changed strings for translation.

This command is typically run by translators or build systems whenever the source documentation is updated, ensuring that the translation efforts remain aligned with the source content.

po4a-updatepo relies heavily on a correctly configured po4a.conf file. Incorrect paths, formats, or processing options in the configuration can lead to errors or unexpected behavior. Always ensure your configuration is up-to-date and matches your document structure.

While po4a-updatepo tries to preserve existing translations, it's always recommended to use version control (e.g., Git) for your source documents and translation files. This provides a robust way to revert changes if something goes wrong during the update process.

The config_file argument is mandatory and specifies the path to a po4a configuration file, typically named po4a.conf. This file defines the relationship between your source documents and their corresponding PO translation files. It specifies:
- The original document format (e.g., man, sgml, docbook, pod).
- The path to the source document.
- The path to the PO file to be updated.
- Options for parsing and handling the specific document type.
po4a-updatepo reads this file to determine which documents to process and how to perform the update. Without a valid configuration, the command cannot function.

The po4a project, which includes po4a-updatepo, was initiated by Martin Quinson around 2002-2003 with the goal of facilitating the translation of various document formats using the Gettext PO file standard. It aimed to bridge the gap between document processing tools and traditional translation workflows. Over the years, it has been actively maintained and extended by various developers, notably Norbert Preining, becoming a robust and widely used tool for internationalizing documentation in open-source projects.

po4a(7), po4a-gettextize(1), po4a-translate(1), po4a-normalize(1), po4a-build(1), po4a-display-strings(1), po4a-compress-infos(1), po4a.conf(5), msgmerge(1), xgettext(1)