GNU PO Guide: msgid, msgstr, Plurals and Context

Last reviewed: 4 October 2026

Short answer

Keep the source identity and context in a PO catalog, translate msgstr, and review format arguments and plural entries under the project's gettext conventions. Extract messages into a template, merge source changes into the language catalog, resolve fuzzy and missing entries, then compile and test the product. A nonempty translation is not automatically approved, and a compiled catalog does not prove the interface uses it correctly.

Key takeaways

Preserve source messages and context unless engineering changes them.
Treat comments and references as useful review information.
Use the target language's plural header and appropriate entries.
Review fuzzy suggestions against the changed source.
Check formatting before compiling release resources.
Verify the application's catalog loading and screen behavior.

What are PO and POT files for?

A PO file is an editable translation catalog for a target language. A POT file is a template used to carry extracted source messages into that workflow. Keep both connected to the source revision so updates can be traced rather than guessed.

GNU's documentation describes entries that relate the original msgid to the translated msgstr, with optional comments, references and flags.[1] Translators normally work on the approved target text, while extraction and merge tools maintain the source relationship.

Do not use the catalog as a place to rewrite product behavior independently of engineering. If the source says a request has been received, the target should not say it has been commercially approved. If the source is unclear or incorrect, raise a query and record the resolution so both languages can be fixed coherently.

How should message identity and context be handled?

Treat source text and its context as the lookup contract. GNU provides msgctxt to distinguish messages that share the same source wording.[2] Choose a stable meaning-oriented context rather than one that changes every time a file is renamed.

For example, “Open” can be a document action or a request status. The action can become “Mở”; a status meaning that a request is not closed can become “Chưa đóng.” Do not reuse the action's translation for the status merely because the English string is identical.

The following original catalog combines a UTF-8 header, contextual entries and a counted message. It is a small teaching fixture, not a complete production catalog with every organizational header field.

msgid ""
msgstr ""
"Project-Id-Version: example 1.0\n"
"Language: vi\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=1; plural=0;\n"

#. Button that opens the selected document.
msgctxt "document.action"
msgid "Open"
msgstr "Mở"

#. Request status: the request has not been closed.
msgctxt "request.status"
msgid "Open"
msgstr "Chưa đóng"

#. Number of documents included in this request.
#, c-format
msgid "%d document"
msgid_plural "%d documents"
msgstr[0] "%d tài liệu"

The comments explain the intended interpretation. The second entry deliberately does not imply that staff are actively processing the request. If the product has a different meaning for its open status, the context and translation need review.

How should Vietnamese plurals be represented?

Use the target catalog's plural rules while preserving the source singular and plural identities. GNU's plural-form guidance lists Vietnamese among languages using one form, with nplurals=1; plural=0;.[3] That is the basis of the fixture's indexed target entry.

The application still needs to pass the count through the expected lookup and formatting path. One target form does not mean the count can be removed. The message “3 tài liệu” remains different from an uncounted label, and zero may need a separate product message if the interface explains an empty state.

Test zero, one and several documents. Check the actual text and the surrounding screen, not just the header. If the product supports other languages, do not copy the Vietnamese header into them. Each catalog needs the appropriate rule and entries for its own language.

How do format arguments affect translation?

Preserve the format contract while translating the sentence. In the fixture, %d represents an integer supplied by the program. The target keeps the same argument type; translating it into another letter would change the formatter's behavior.

GNU's msgfmt documentation describes format checks for marked entries and the broader --check option.[4] Apply the appropriate checks in the actual project's tooling. Different languages or frameworks can use different formatting conventions, so identify the correct flags rather than marking every string indiscriminately.

For messages with multiple values, consider the supported positional syntax and test reordering carefully. A person's name, file count and deadline can change order in Vietnamese. Do not solve that by splitting a complete sentence into fragments that cannot be rearranged naturally.

Catalog component	Linguistic work	Protected contract
msgid	Understand the source and raise queries	Source identity maintained by workflow
msgctxt	Use it to resolve ambiguity	Stable context expected by lookup
msgstr	Translate and review the target	Meaning and allowed formatting
Format argument	Place it naturally when supported	Type, identifier and required arguments
Plural entry	Review each required target form	Header and indexed structure
Comments and references	Use relevant context	Information needed for later review

What do comments and fuzzy entries tell reviewers?

Comments explain context; flags can carry workflow or format information. GNU documents the comment forms associated with PO entries.[1] Preserve the useful source and translator information rather than converting the catalog into text pairs that lose those distinctions.

A fuzzy entry is a review signal, not proof of completion. GNU explains that merging changed source can produce a suggested association with an earlier translation, which then needs revision.[5] Compare the new source, old wording and context before accepting it.

Do not clear the fuzzy flag in bulk merely to make a completion percentage look better. Resolve the linguistic question, record any terminology decision, and then update the status according to the workflow. A small source edit can reverse an instruction, alter a limit or change the confirmed state.

Also keep missing and obsolete messages visible in the review process. Decide how the application should behave when a translation is unavailable and who may remove entries no longer extracted. Avoid deleting historical context before confirming that the resource is no longer used.

How should extraction and merging work?

Extract the project's marked messages into a template, then merge that template into each language catalog. GNU documents xgettext for extraction and msgmerge for catalog updates.[6][7] The exact invocation depends on the source language, wrappers and build arrangement.

These illustrative shell commands assume C sources and the named gettext calls. They are workflow examples, not commands executed against a customer application for this article.

xgettext --language=C --keyword=gettext --keyword=ngettext:1,2 --keyword=pgettext:1c,2 --output=messages.pot src/*.c
msgmerge --output-file=app_vi.updated.po app_vi.po messages.pot
msgfmt --check --statistics --output-file=app_vi.mo app_vi.updated.po

The merge writes a separate updated catalog so the original remains available for comparison. Review the diff before replacing the approved resource. Confirm that custom wrappers are extracted, not just direct gettext calls, and that dynamic source expressions are handled according to the project's supported approach.

Compilation belongs after review. The command line cannot decide whether “Chưa đóng” is the right product status; it can check supported structural and format rules. Keep human approval and technical checks connected without pretending they are the same step.

How should encoding and multiline messages be reviewed?

Use the project's declared encoding consistently and verify the Vietnamese text after the complete export-and-import path. The fixture declares UTF-8. A catalog can look correct in one editor while another step interprets its bytes differently.

Treat quoted continuation lines and escape sequences carefully. Several quoted lines may contribute to one logical message rather than separate screen lines. An encoded \n can represent a new-line character, but the final display still depends on the application rendering context.

Do not edit quotes and escapes through a broad replacement that also changes syntax. Use a PO-aware editor where practical, then apply the project's validation. Check Vietnamese diacritics, punctuation, long strings and copied text in the running interface, not only in the catalog view.

What should the release QA checklist cover?

Check identity, meaning, technical format and product loading separately. Each check needs a specific reproduction case. The following original matrix is designed for a representative fixture and can be expanded for the real application.

Check	Reproduction case	Expected evidence
Source revision	Compare extraction with release source	Catalog is based on the intended revision
Context	Look up both Open entries	Action and status remain distinct
Arguments	Render integer and string messages	Types and required values are preserved
Counts	Request zero, one and several documents	Appropriate target message and count
Review status	Inspect fuzzy and missing entries	Policy exceptions are explicit
Encoding	Read and render Vietnamese text	Diacritics survive the pipeline
Loading	Start the app in the target language	Correct catalog and domain are used
Interface	Exercise representative screens	Text is meaningful, readable and operable

Add a changed source message to the fixture and repeat the merge. Check that reviewers see the change and do not inherit approval blindly. Also test the application's fallback behavior when a message is missing; a fallback that is useful during development may not satisfy the agreed release criteria.

How should LocalizeZone projects hand off PO resources?

Provide the catalog, template, source revision and conventions alongside screenshots and terminology. LocalizeZone recommends explaining the extraction markers, format flags and runtime loader in the software localization brief. State whether the scope includes catalog review, technical checks or testing in a runnable build.

Send representative files and known issues through the quotation page. A source-ambiguous project needs time for queries; a catalog with many changed entries needs review rather than only word replacement. Clear input helps the proposed scope reflect the work that protects the release.

Maintain the approved catalog and the update process together. Future source changes should trigger extraction, merge, review and relevant QA again. Avoid treating localization as a one-time file delivery when the product continues to add or change messages.

FAQ

Should a translator rewrite msgid?

Usually not. Source identity comes from the application workflow. Raise source issues and let engineering update the source and template coherently.

Why can Open have two translations?

Its meaning differs between an action and a status. msgctxt keeps those lookup identities distinct so each can have the appropriate target.[2]

Does one Vietnamese plural form remove count testing?

No. Verify count lookup, formatting and empty-state behavior. The count is still meaningful even when the same target noun is used.

Is a fuzzy suggestion ready to publish?

No. It needs review against the changed source and context.[5] Follow the project's approval policy before using it in a release.

Does a compiled MO file prove the translation is correct?

No. It proves only the checks that were actually performed during compilation. Confirm linguistic meaning, loading and interface behavior separately.

What makes a quotation more accurate?

Provide PO and POT samples, screenshots, source revision, target languages and required review layers. Include custom extraction or formatting conventions and expected release timing.

Sources and methodology

Official GNU gettext manual pages were checked on 4 October 2026, using privately saved copies when browser retrieval timed out. The Vietnamese catalog, workflow commands and QA matrix are original examples. A local fixture check is not a report that GNU command-line format checks or an application build were executed; production extraction, merging, compilation and rendering still require the project's actual environment.

References

[1] GNU gettext manual. What an entry looks like.

[2] GNU gettext manual. Using contexts for solving ambiguities.

[3] GNU gettext manual. Additional functions for plural forms.

[4] GNU gettext manual. Invoking the msgfmt program.

[5] GNU gettext manual. Fuzzy entries.

[6] GNU gettext manual. Invoking the xgettext program.

[7] GNU gettext manual. Invoking the msgmerge program.

GNU PO Localization Guide: msgid, msgstr, Plurals and Context