[derek73]

Closes #1108.

Adds locales.VI, a Vietnamese pack:

from nameparser import parser_for, locales
anh = parser_for(locales.VI).parse("Nguyen Van Anh")
anh.family, anh.middle, anh.given   # ('Nguyen', 'Van', 'Anh')

1.4.0 through 2.8.0, and the default, read Nguyen Van Anh as given Nguyen, family Van Anh.

What the pack is

• A plain choice of vi, with no strict mode. Its order comes from vi.toml's new [rules] table (name_order = "family-first-given-last").

• Titles vi.toml turns on, each default = false: the academic titles written before a name (ts, ths, gs, pgs, which also read the stacked PGS.TS. and GS.TS.) and the office đbqh with its ASCII spelling dbqh. bs is excluded, because preferred under the choice it evicted en.toml's credential BS.

• A lexicon fragment that removes the readings other files give Vietnamese syllables:

  • particles: van le do du di la tho da san
  • connectives: the y
  • credentials: do ba chi

  This is the one pack fragment that removes. Should parser_for(locales.VI) read Nguyen Van Anh as family Nguyen, middle Van, given Anh, and Le Van Anh as family Le? #1108 assumed a given reading in vi.toml would win over the Dutch van, but choose prefers only by a vocabulary reading, and a name reading never settles a clash (decision 15). The pack therefore bends decisions 6 and 15 for this one pack: its order already commits a caller to Vietnamese names. mechanisms.md#LOCALE-PACKS-PURE-DATA's contract names the exception.

• The default parse does not move. _compiled.py and snapshot.jsonl are unchanged.

Measured

On the local corpora #1110 added, scoring each record's parts derived from its order. Columns are default / the order alone / VI / strict VI.

Population	Default	Order alone	VI	Strict VI
UIT-ViNames, 21,090 names	13	21,065	21,085	21,089
UIT-ViNames, diacritics stripped	89	19,221	21,082	21,089
National Assembly deputies, 499	0	483	499	499

• With diacritics stripped, the order alone to VI is +1,861 / −0.
• PSC's Vietnamese nationals, filed in Western order, are the contrast set. The order loses them, and the pack adds no loss beyond the order's.
• The per-word table, the credential gains and costs, and the recipes are in decisions/vocabulary-model's 2026-11-05 Should parser_for(locales.VI) read Nguyen Van Anh as family Nguyen, middle Van, given Anh, and Le Van Anh as family Le? #1108 entry.

Accepted costs, each pinned by a test row:

• A lone word reads as the family. Anh → family Anh, under rules/O5 (the lone name word's convention). Should a lone name word read as the given name under a family-first pack, so parser_for(locales.VI).parse("Anh") gives given Anh? #1111 asks for a Policy setting for this.
• The credentials written for English-language readers. DO or BA after a Vietnamese name reads as a name word, with a comma or without (Nguyen Van Anh, DO → given DO), and CHI without a comma. That is 4 DO and 1 BA among ctgov and FEC names with a Vietnamese surname, each written given-first, which VI misreads anyway.
• The removals act after a family comma. Beethoven, Ludwig van → middle van.
• A trailing stacked title reads as the given name (Nguyen Van Anh PGS.TS.). No corpus writes one; all 16 found are leading.

Kept: after a family comma, the given part reads given-first. FEC's Vietnamese-surname donors write the given part Western-style 69 to 12 in native order.

CLDR's per-pack view: vi reads 16 of 24 renderings by default and 10 of 24 with the pack.

Also in this PR

• config_diff.py diff --spelling stripped,upper,lower rewrites every name before it is read, so the romanized and one-case views recompute from the repository.
• Tests that used vi as the stock file with no readings now use hu.
• _surface_deviates (tests/v2/test_locales.py) matches a title phrase of two adjacent words. VI's office makes the first phrases a choice changes (chief đbqh).
• tests/v2/rules_budget.json is re-recorded: rules/O5 gains one Accepted clause reading O5's own signal (one name word).
• nameparser/vocab/AGENTS.md records the lesson: a reading taken out leaves the readings it overrode to act.

Reviews

Round	Review	Outcome
1	code-reviewer	README available() doctest missing vi (a CI failure); NGUYEN VAN DO reading suffix DO under the pack, which led to the credential removals after measurement; the PGS.TS.BS. claim; the recipe not in the repository; stale --locale help, AGENTS.md and RFC text. All fixed.
1	pr-test-analyzer	Eight of eleven removals were pinned only by a set assertion. A per-removal negative-control test was added, plus rows for each syllable, the comma shapes with titles, and the head titles.
1	comment-analyzer	Rotator comments claimed witnesses they lacked; vetting notes overstated their sources. Fixed.
1	design-docs-reviewer	Decision 6 and two Standing lines contradicted the exception (head notes added); the CLDR lone-word cost was 2, not 6; the recipe. Fixed.
1	/simplify	Cached parsers in tests, one normalization per piece, phrases folded into held. Applied.
2	code-reviewer	The credential cost was wider than stated; --spelling stripped broke Hangul and kana. Both measured and fixed (only marks on Latin letters are dropped). ma was measured at 0 gained and 1 cost, and is left out.
2	pr-test-analyzer	Positive control added; credential cost shapes pinned; lowercase đ and Hangul rows added.
2	comment-analyzer	The comma-name scope and the Y note corrected; the stacked-title comment now quotes H5.
2	design-docs-reviewer	The ground for the exception was false for comma names, now recorded as an accepted cost; exact per-corpus credential counts with the comparator; a recipe that runs; decision 15's note names the credentials.
2	/simplify	dataclasses.replace for the control pack applied. The _unmarked reuse was superseded by the Latin-only fix.
3	code-reviewer, on the last fix commit	CHI after a comma stays a suffix: the capitals shape (rules/C6) takes any three-letter word in capitals there, whatever the vocabulary. The prose now says CHI reads as a name word only without a comma, and a test row pins the boundary. Everything else verified, including every row and the recipe's figures.

Checks: uv run pytest, -n0 -m serial, Python 3.15 in its own environment, mypy, ruff check, tools/vocab/build.py --check, sphinx-build -b doctest docs, python -m doctest README.rst.

🤖 Generated with Claude Code