msgmerge

Update a translation file

$ msgmerge [[-U|--update]] [path/to/file.po] [path/to/messages.pot]

$ msgmerge [[-h|--help]]

msgmerge [OPTION]... EXISTING-POFILE TEMPLATE-POFILE

--force-po
    Force writing of a PO file, even if it has no messages.

--lang=LANGUAGE
    Specify target language. Used for plural forms.

--previous
    Retain previous msgids of fuzzy entries. Highly recommended for translators.

--no-fuzzy-matching
    Do not attempt fuzzy matching. New strings are untranslated.

--add-location
    Add #: file:line style location lines to the output.

--no-location
    Do not add #: file:line style location lines to the output.

--sort-output
    Sort output entries by msgid.

--sort-by-file
    Sort output entries by source file location.

--color[=WHEN]
    Use color to highlight messages; WHEN can be always, never, or auto.

--silent, -s
    Suppress warnings.

--verbose, -v
    Print verbose messages.

--backup=CONTROL
    Make a backup of EXISTING-POFILE. CONTROL specifies backup policy.

--no-backup
    Do not make any backup.

--suffix=SUFFIX
    Override the usual backup suffix.

--directory=DIR, -D DIR
    Add DIR to the list of directories scanned for dependencies.

--width=NUMBER
    Set output page width for PO files.

--indent
    Indent the body of the msgstr lines in multiline entries.

--no-indent
    Do not indent the body of the msgstr lines.

--strict
    Operate in strict mode (e.g., check for syntax errors).

--warn-format
    Warn about suspicious printf format strings.

--warn-domain
    Warn about unknown domains in #| msgid comments.

--statistics
    Print statistics about the number of translated/untranslated entries.

--version, -V
    Display version information.

--help
    Display help and exit.

msgmerge is a crucial utility within the GNU Gettext internationalization (i18n) framework. Its primary function is to update an existing translation catalog file (a .po file) with new messages or changes from another source, typically a .pot (Portable Object Template) file or another .po file. This process is essential for maintaining translations as software evolves and source code changes.

When msgmerge is run, it compares the messages in the target .po file with the messages in the new template. It adds new messages, removes obsolete ones, and updates existing messages that have changed in the source. For changed messages, msgmerge attempts to provide a "fuzzy" translation, marking the message as needing review by a human translator. This preserves the previous translation as a guide, significantly reducing the manual effort required to keep translations current. It ensures that translators only need to focus on new or modified strings, rather than re-translating the entire application.

• Fuzzy Translations: While helpful, "fuzzy" matches are not perfect and always require manual review by a human translator to ensure accuracy and contextual correctness.
• Context Changes: If a message's context changes significantly without its msgid changing, msgmerge might not identify it as a changed message, potentially leading to incorrect translations.
• Plural Forms: Correct handling of plural forms relies on accurate Plural-Forms headers in the PO files and can be a source of errors if misconfigured.
• Encoding: Ensure consistent character encoding across all input files to prevent garbled text.

msgmerge takes two primary arguments: an EXISTING-POFILE (the translation file to be updated) and a TEMPLATE-POFILE (usually a .pot file generated by xgettext or a .po file from another source). The output is written to the EXISTING-POFILE by default, overwriting it.

This option is highly recommended for translators. When a message is updated and marked as "fuzzy," msgmerge normally includes the old msgid in a #| msgid comment. --previous ensures that the previous translation (the msgstr before the merge) is also included as a comment, making it easier for translators to see what changed and quickly adapt the translation.

When msgmerge finds a message that has changed slightly but is still recognizable, it marks the corresponding translation as "fuzzy." This means the translation might be close but requires human verification. Fuzzy entries are often excluded by msgfmt unless explicitly told to include them, ensuring that unverified translations do not end up in the final compiled translation file.

msgmerge is an integral part of the GNU Gettext utilities, a project initiated in the early 1990s to provide a standard framework for internationalization and localization (i18n/l10n) in free software. Its development aimed to streamline the translation update process, a common bottleneck as software evolves rapidly. Before tools like msgmerge, updating translations often meant re-translating entire files or painstaking manual comparison. By intelligently merging new templates with existing translations, msgmerge significantly improved the efficiency and maintainability of multilingual software projects, becoming a cornerstone for translators working with Gettext.

xgettext(1), msgfmt(1), msginit(1), msgcat(1), msguniq(1), gettext(1)