A translator working in a .po file is editing markup as well as prose,
and the ways that goes wrong are few and specific. Each rule was
measured against the nine languages here before being kept.
Errors, which change the document's structure and so its object
numbering:
empty-after-trim a whitespace-only msgstr. sisu reads a
whitespace-only line as blank, the paragraph
ceases to exist, and every object number after
it shifts. Leaving the msgstr empty is the fix:
untranslated falls back to the source text and
the object survives.
heading-mismatch heading markup on one side only, so a
paragraph becomes a heading and the document
grows a section the source does not have.
blank-line a blank line added or removed inside a msgstr,
splitting one object into two.
yaml-key a header entry whose yaml keys differ from the
source. The header is configuration: translate
the values, never the keys.
Warnings, which change what the text says or links to but not its shape:
a ${} substitution, a {text}#anchor target, or an inline markup count
differing between source and translation.
Fuzzy entries are skipped. Fuzzy already means not used and needing
review, and po4a will not put one in the output, so checking them
reports faults nobody relies on.
Over 6653 translated entries the errors fire twice, and both are real:
the ja msgstr of " " that costs two objects from ocn 818, and the pl
paragraph translated as "2~ Wcięcia" that becomes a heading.
Two rules needed calibrating rather than guessing. The anchor rule first
reported 293 by taking a full stop after a link as part of the anchor;
corrected it reports 69. The yaml-key rule first reported 20, every one
of them prose from the style guide reading "produces: *{foo}* or
!{foo}!", which any shape test takes for a key; it now applies only to a
master file's catalogue, where a document header is the only thing that
can appear.
Exit is 1 on any error and 0 otherwise, so it can gate a commit.
(assisted by Claude-Code)