mend the ja and pl translations that broke ocn alignment The languages of a document share their object numbering, and two of live-manual's did not. ja/project_git.ssi.po had msgstr " " against msgid "Or,". One space. po4a emits it, a line of one space is not an object, and the entry serves two places, so Japanese was two objects short of English and everything below was renumbered. An empty msgstr is the value gettext already has for this: untranslated, the English comes back, the object survives and the gap is visible so that somebody translates it. pl/user_overview.ssi.po had msgstr "2~ Wcięcia" against a paragraph. That string is a heading belonging to another file, project_coding- style.ssi.po, where it sits against its right msgid: a paste into the wrong entry. So Polish had a heading where every other language has a paragraph, and the paragraph's translation never existed. Emptied for the same reason; the heading translation stays where it belongs. The generated .ssi files are edited to match, po4a not being available here. Not guessed: "Or," appears untranslated in ro and pt_BR, and the paragraph appears untranslated in de, it, pt_BR and ro byte identically in all four, so the wrapping is po4a's own. msgfmt --check passes on both catalogues, and the lint that named these two reports no errors at all now. (assisted by Claude-Code)
The question before any translation work is where the effort should go, and a .po file does not answer it by looking at it. lang total done fuzzy empty translated ca 1106 1105 0 1 99.9% es 1106 1105 0 1 99.9% fr 1106 1105 0 1 99.9% ja 1106 1104 1 1 99.8% pl 1106 924 21 161 83.5% it 1106 809 147 150 73.1% pt_BR 1106 251 83 772 22.7% ro 1106 140 25 941 12.7% de 1106 110 5 991 9.9% Fuzzy is the column worth reading. Those are translations that exist, that a source edit has taken out of use, and that po4a will not put in the document. it is carrying 147 and pt_BR 83: clearing a fuzzy flag is a reviewer's job rather than a translator's, and it is much cheaper than the 991 empty entries de is carrying. It counts by parsing rather than by matching lines, which matters here: a msgstr "" on its own line opens a multi-line translation and is not an empty one, so counting those lines reports every translation long enough to wrap as missing. Counted that way ca looks 45% translated; it is 99.9%. (assisted by Claude-Code)
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)
The catalogues dated from 2015 and the document header had moved on: from the bespoke sisu form to spine's yaml. Regenerating brings them up to the English as it stands and puts them in step with the header for the first time. The body came through untouched. Only the nine live-manual.ssm files changed, and po4a discarded nothing. Five entries per language, the same five in all nine, had gone fuzzy: the header blocks. The reason is visible in the fuzzy entries themselves, which record the old string as a single line, creator: "...", where the header now wants a block with an indented author:. Those five are mended rather than dropped. Two carried translation and were reshaped into the yaml the header uses; three were never translatable content at all, being a version marker, an iso date, and a make block of regexes, and now take the source, so that a regeneration stops offering them for translation. What this revealed: the translated headers were correct spine yaml carrying translated text, while their catalogues held the old form. So they were not produced by po4a at all, but maintained by hand after the yaml change, and the two have been out of step ever since. Nothing said so until something regenerated. Three languages gain a licence in their own language. de, pt_BR and ro each had one in the catalogue and an English one in the header, because the header was written before the catalogue said otherwise. Two corrections while reshaping: es carried a doubled space in the project name that the hand-kept header did not, and pl had translated the copyright holder where the rule took the source. Both follow the catalogue now, which is authoritative. The copyright line follows the English in dropping its "Copyright (C)" prefix. Every catalogue passes msgfmt --check. (assisted by Claude-Code)
The po4a working set moves from media/text/{pot,po} to
tools/po4a/{pot,po}: the layout this repository's .gitignore has
specified since before it was needed, at the pod root under tools/
media/ is what the document is; tools/ is what was used to make parts of
it. A .pot and .po pair is a gettext artefact rather than sisu markup,
and naming the tool under tools/ scopes it as that tool's working files
rather than claiming to be the document's own content.
The whitelist needed no change and the filenames needed no renaming:
*.ssi.pot, *.ssm.pot and index.html.in.pot are what po4a already
produced.
media/text/ keeps bin/, Makefile, _sisu/ and the two lm_sdp text files
for now. None is markup and none is carried. Whether the helpers are
carried later is open; this commit is about the catalogues.
nothing reads these files yet (spine output is unaffected)
(assisted by Claude-Code)
The pod carried a full pt_BR text tree, twenty files with the same structure as the English, and a translation catalogue, while pod.manifest did not list the language. Its abstraction comes out with the same object count as the seven currently aligned languages, it shares object numbering with the English as it stands. (assisted by Claude-Code)