M4: glossary

[tamnd]

The glossary. Spends model calls.

The glossary is the one artefact of this project that cannot be repaired afterwards. A mistranslated sentence is one entry to fix. A term rendered wrong is every entry that used it, across 548 files, and nobody finds out until a reader searches for the right Vietnamese word and gets nothing back.

Checklist

• glossary.py: the row model, keep_en, context, version, diff
• The matcher: one implementation, three callers, being the prompt builder, the G02 audit rule and stale --glossary, with one shared test suite
• glossary mine: the four sources in trust order, human translations first and raw frequency last
• glossary curate: batches of 40, the G-a through G-f checks, and an explicit way for the model to answer that it does not know
• A human pass over the flagged rows and the top 200 terms by corpus frequency
• glossary.yaml v1 and GLOSSARY.md regenerated from it, with G05 passing
• Retire scripts/mt*.py to legacy/ in the content repo with a note saying what replaced them

Exit

glossary.yaml v1 with a real curated term set including the keep_en decisions. Every row passes G-a through G-f. The existing style rules in GLOSSARY.md are preserved word for word and its table is generated from the YAML. Term count, how many came from each of the four sources, and how many the model declined to guess, all in a comment on this issue.

[tamnd]

Done in #21 (the tool) and tamnd/python-docs-vi-machine-translation#44 (the term list itself). Retiring the old scripts was tamnd/python-docs-vi-machine-translation#43.

glossary.yaml is at version 1 with 639 terms, 52 of them keep_en, 0 contextual.

Where the candidates came from

glossary mine proposed 1,010, in trust order:

source	candidates
human translation	83
glossary.po	163
corpus frequency	764
machine disagreement	0

Machine disagreement found 2 phrases the old pipeline had rendered more than one way, and both were already known to a more trusted source, so it contributed no rows of its own. That is the source working as intended rather than failing: it only earns a row when the other three have no reason to notice the term.

What the model did with them

26 calls, batches of 40, 3,887 seconds.

• 950 accepted
• 24 declined, which is the model using the "I do not know" answer rather than guessing
• 36 dropped by the checks before I ever saw them, 4 on G-b and 32 on G-c
• 0 dropped under call

What the human pass took out

The model was reliable about Vietnamese and unreliable about what counts as a term, so the review pass was mostly deletion. 311 rows struck in six classes:

class	rows
a sentence fragment	92
changelog prose	61
a contributor name	51
a fragment of example code	44
a token the miner cut in half	35
the title of a page or a section	28

Plus 4 duplicates removed and 10 rows added by hand, leaving 645. Six more went during collision resolution and the check against human work below, which is where 639 comes from.

The 35 mangled tokens were the miner's fault, not the model's. encoding utf-, ipv addresses, py ssize, def init: a tokeniser that took letters and skipped everything else does not skip utf-8, it takes utf- out of the middle of it. Fixed in #21 along with two other things this run turned up, being G-e rejecting a singular sitting beside its own plural, and G05 telling you to run a --fix flag that did not exist.

Checking it against work humans already did

The mechanical checks say a row is well formed. They cannot say it is right. So I ran the finished contract over the 1,435 human-translated entries in the content repo and counted how often the human agreed with it: 975 of 1,247 occurrences, 78%.

Three rows had zero agreement in three or more places, and all three turned out to be the substring test not allowing for "các", so the humans did agree. Five rows were genuinely wrong, and nothing but real translated text was ever going to catch them:

term	the row said	humans write	score
file	tệp tin	tệp	12 of 56
iterable	có thể lặp	khả lặp	0 of 25
slice	lát cắt	phần cắt	0 of 6
index	chỉ mục	chỉ số	0 of 5
docstring	chuỗi tài liệu	docstring	0 of 4

The same measurement settled two places where the curated rows and the hand-written style guide in GLOSSARY.md disagreed. On built-in the guide was right and the curation wrong, tích hợp sẵn 31 against dựng sẵn 0. On file the curation was right and the guide stale, tệp 20 against tập tin 0. Both sides now say the same thing.

GLOSSARY.md keeps its existing style rules word for word. The generated table sits above them under "The term list" and the two hand-written tables are now "Notes on terms that are easy to get wrong", which is what they always were.

Two follow-ups worth their own issues, both found by doing this rather than by thinking about it. A check for a singular and plural whose renderings differ by more than "các", which would have caught the three rows above without my reading them. And a command that runs the contract against the human corpus, so the 78% is a number anyone can recompute instead of a number I once measured.

sequence is rendered "dãy" and I am not certain that is better than "chuỗi" here. Flagged for a native reviewer rather than quietly picked.

Suite green, coverage 98% against the 85% floor, mypy --strict clean on 23 files.