From 880f5b677e4d74c2f59f913930f056860455c4be Mon Sep 17 00:00:00 2001 From: Doxa Maps Date: Sun, 27 Sep 2026 03:35:58 +0000 Subject: [PATCH] Say where the country-name helper must not be used It has no consumer yet, and that is deliberate rather than unfinished. Intl's English names differ from the canonical names in library/data/countries.json for 42 of 242 countries -- "Antigua & Barbuda" vs "Antigua and Barbuda", "Cape Verde" vs "Cabo Verde", "Hong Kong SAR China" vs "Hong Kong", "Myanmar (Burma)" vs "Myanmar". So it is not a drop-in replacement for a name already on screen. The regions surfaces prefer the API's localized label on purpose (region-dashboards.vue:370) and are measured against live doxa.life; swapping the source would change 42 English names and break clone parity. Which name is canonical is a product decision, not a refactor. Its real gap is the case where only an alpha-3 is in hand, or where a label arrives in English whatever the reader's locale. Recorded in the file because the failure mode is silent -- the wrong names still look like names. --- library/utils/countryName.js | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/library/utils/countryName.js b/library/utils/countryName.js index 4805a70e2..16ac44a0f 100644 --- a/library/utils/countryName.js +++ b/library/utils/countryName.js @@ -20,6 +20,22 @@ * 3. the alpha-3 code itself, so something identifiable always renders * * No i18n framework is required: this reads a locale STRING the caller already has. + * + * ★★ WHERE NOT TO USE THIS, MEASURED. It has NO consumer yet on purpose. Intl's English names + * differ from the canonical names in library/data/countries.json for 42 OF 242 COUNTRIES -- "Antigua & + * Barbuda" vs "Antigua and Barbuda", "Cape Verde" vs "Cabo Verde", "Hong Kong SAR China" vs "Hong + * Kong", "Myanmar (Burma)" vs "Myanmar", "Caribbean Netherlands" vs "Bonaire, Sint Eustatius, and + * Saba". So this is NOT a drop-in replacement for a name we already display: + * + * ✗ do NOT swap it in where an API already returns a LOCALIZED label. region-dashboards.vue:370 + * prefers the API's label deliberately, and the regions surfaces are measured against live + * doxa.life -- switching the source would change 42 English names and break clone parity, which + * is a product decision about which name is canonical, not a refactor. + * ✓ DO use it where the only thing in hand is an alpha-3 and there is no label at all, or where + * a label arrives in English regardless of the reader's locale. That is the gap it was built for. + * + * Stated here rather than left to be discovered, because the failure mode is silent: the names all + * still look like names. */ import table from '../data/iso3-to-alpha2.json' import countries from '../data/countries.json'