Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(ok): make locale promotion a real process (PRD-7854) (#3293)
Andrew Mikofalvyf5663253fd79
diff --git a/packages/app/src/locales/GLOSSARY.md b/packages/app/src/locales/GLOSSARY.mdindex 28144241a..0a52887e9 100644--- a/packages/app/src/locales/GLOSSARY.md+++ b/packages/app/src/locales/GLOSSARY.md@@ -14,6 +14,8 @@ each time.Eight nouns is deliberately small — under a hundred cells against ~2,800 catalog entries perlocale. It is the one artifact in this system short enough for a native speaker to review endto end, which is what makes it worth more than the same effort spread over the catalogs.+That review, and what it takes to get a locale into the language picker, is+[`REVIEW.md`](./REVIEW.md).## Never translateddiff --git a/packages/app/src/locales/REVIEW.md b/packages/app/src/locales/REVIEW.mdnew file mode 100644index 000000000..40f0be74d--- /dev/null+++ b/packages/app/src/locales/REVIEW.md@@ -0,0 +1,141 @@+# Locale review and promotion++OpenKnowledge enumerates eleven interface locales and offers three of them in the language+picker. The other eight have complete catalogs that nobody can select. That gap is deliberate,+and this file is how a locale crosses it.++Completeness is not the bar. Every catalog in `src/locales/` is full, because the agent that+writes a string writes its ten translations in the same change. What ten of them have not had is+a reader — someone who reads the language telling us the words are right. Offering a language in+the picker is standing behind it, and we can only stand behind what someone has read.++So: **a locale enters the picker when someone who reads it has reviewed it.** Nothing else+promotes one. Not 100% coverage, not a green CI run, not another model agreeing with the first.++## The state of each locale++| Locale | Language | Status | Basis | Evidence | Blocked by |+| --- | --- | --- | --- | --- | --- |+| `en` | English | source | — | — | — |+| `es` | español | vouched | A Spanish-reading team member | Audited in-product during the initial rollout; no packet review on record | — |+| `zh-Hans` | 简体中文 | vouched | Requested externally; serves as the coverage instrument | Stray English is unmissable inside Han script, so coverage is verified — but no reader of Chinese has judged the wording | — |+| `zh-Hant` | 繁體中文 | unreviewed | — | — | — |+| `hi` | हिन्दी | unreviewed | — | — | — |+| `ar` | العربية | unreviewed | — | — | right-to-left layout |+| `fr` | français | unreviewed | — | — | — |+| `bn` | বাংলা | unreviewed | — | — | — |+| `pt-BR` | português (Brasil) | unreviewed | — | — | — |+| `id` | Indonesia | unreviewed | — | — | — |+| `ur` | اردو | unreviewed | — | — | right-to-left layout |++`source` is the catalog whose `msgstr` is the English text itself; there is nothing to review.++`unreviewed` is a complete, machine-checked catalog no native reader has seen. Eight of eleven.++`reviewed` is the bar this file describes: someone who reads the language read it and said so+where a stranger can find it. **No locale holds this status yet.** The first one to earn it will+be the first promotion this process actually produced.++`vouched` is weaker, and exists so the two locales that shipped in the picker before this process+did are recorded truthfully rather than rounded up. Neither has had a native review; each was+offered for a stated reason that is not one. Recording it this way is not an accusation, it is+the point of having a record: `zh-Hans` in particular is the locale most likely to have real+users and the one with no reader, which makes it the obvious first packet to send out.++A **blocker** is a reason the locale cannot be offered even with a clean review. Both current+blockers are the same one: the chrome still lays out with physical margins and insets rather than+logical ones, so a right-to-left base direction over it is visibly wrong rather than merely+unpolished. That is a layout problem no translation fixes, and it is deferred until an+Arabic- or Urdu-reading user or contributor appears. Their catalogs stay complete and+freshness-gated in the meantime.++Those two are also the reason the packet is a file rather than an instruction to run the app: a+contributor who opened OpenKnowledge in Arabic today would be looking at a broken layout, so+"run it in your language and tell us how it reads" is advice that works for eight locales and+fails for the two that need it most. A packet works for all ten.++This table is parsed, not just read: `scripts/generate-locale-review-packet.mjs` refuses to build+a packet for a locale with no row here, and `scripts/generate-locale-review-packet.test.mjs` pins+it against `SUPPORTED_LOCALES`, `PICKER_LOCALES` and `LAYOUT_DEFERRED_LOCALES`. A row cannot drift+away from the code it describes without failing the suite.++## Running a review++### 1. Build the packet++```bash+node scripts/generate-locale-review-packet.mjs fr --out /tmp/fr-review.md+```++One Markdown file, no links into a checkout. The reviewer needs a text editor and nothing else —+no clone, no install, no running app. That constraint is the point: the people who can do this+review are not necessarily people who can run the repo.++It samples roughly a hundred strings out of ~2,900, chosen by a fixed rule: the whole locked+glossary, then the glossary words in real messages, then the highest-traffic chrome, shortest+strings first. Asking for 2,900 gets the request declined or skimmed, and a skimmed review of+everything is worth less than a real review of the part that matters. The script's header states+the rule; so does the packet, so the reviewer knows what they are being handed.++A contributor who *can* run the app should also run it in their language — `OK_LANG=fr ok start`+activates any enumerated locale, promoted or not. That is a better review than the packet. The+packet exists so that not being able to do it is not a blocker.++### 2. Send it out++Community translation runs through public pull requests against `inkeep/open-knowledge`. Attach+the packet, or paste it into the issue or PR thread. Ask for what the packet asks for: a list of+numbered strings to change, and what they should say.++### 3. Land what comes back++Corrections are ordinary catalog edits. Fill the `msgstr` in `src/locales/<locale>/messages.po`,+run `pnpm --dir packages/app run i18n` to recompile, and commit the catalogs. If a correction+changes one of the locked nouns, change it in [`GLOSSARY.md`](./GLOSSARY.md) **and sweep every+message in that locale that uses the old form, in the same change** — a half-swept rename leaves+the catalog holding two words for one concept, which is worse than either word alone.++### 4. Record the review++Update this file's table in the same PR: `Status` to `reviewed`, `Basis` to the reviewer's name or+handle, `Evidence` to something a stranger can follow back — a PR number, an issue link, a thread.+"An agent reviewed it" is not evidence and does not count; the entire reason this process exists+is that a model checking another model's translation tells us nothing new.++A review that comes back with corrections is still a review. What decides the status is that a+reader of the language read it, not that they had nothing to say.++`git add` this file before running `pnpm check`. The catalog-drift guard diffs the whole of+`src/locales/` against the index, so an unstaged edit to this file or to `GLOSSARY.md` is+reported as catalog drift and sends you off to re-run an extractor that will change nothing.++## Promoting a locale++One line, in `packages/core/src/i18n/locales.ts` — adding the tag to the tuple. Promoting `fr`+would read:++```ts+export const PICKER_LOCALES = ['en', 'es', 'zh-Hans', 'fr'] as const satisfies readonly SupportedLocale[];+```++That is the whole change. Everything downstream derives from that tuple:++- The Settings picker renders `PICKER_LOCALES`, so the language appears with no UI edit.+- `scripts/check-i18n-picker-completeness.mjs` reads the same tuple and starts gating the new+ locale absolutely — a picker entry backed by a partial catalog fails CI from that commit on.+- `packages/app/tests/meta/supported-locales-sync.test.ts` already pins `SUPPORTED_LOCALES`+ against the Lingui config, so the catalog behind the tuple is guaranteed to exist.++Ship it with the table update in the same PR, so the picker and the record of why it changed+arrive together.++A locale carrying a blocker does not get this change, however clean its review. Record the+review, leave the blocker, and promote when the blocker lifts — a reviewed Arabic catalog behind+a layout that renders it wrongly is still not something to offer anyone.++## Adding a locale nobody asked for++Don't. Every enumerated locale costs a translation on every new string, forever, and buys nothing+until someone reads it. The eight unpromoted catalogs are already more than the review capacity+this project has; adding a twelfth makes the ratio worse, not better. The signal worth acting on+is a person who wants the language and will read it.diff --git a/packages/core/src/i18n/locales.ts b/packages/core/src/i18n/locales.tsindex 7d7a0470c..7518e6c82 100644--- a/packages/core/src/i18n/locales.ts+++ b/packages/core/src/i18n/locales.ts@@ -52,6 +52,11 @@ export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];* A stored preference naming an enumerated-but-unpromoted locale stays valid* and resolves normally — that is what lets a translator run the app in their* own language to check their own work.+ *+ * Adding a tag to this tuple is the whole of a promotion; the picker, the+ * completeness gate and the review record all derive from it. What has to+ * happen first, and what gets recorded, is+ * `packages/app/src/locales/REVIEW.md`.*/export const PICKER_LOCALES = ['en', 'es', 'zh-Hans'] as const satisfies readonly SupportedLocale[];diff --git a/scripts/check-i18n-picker-completeness.mjs b/scripts/check-i18n-picker-completeness.mjsindex 262d1e8e7..cda4e1fa1 100644--- a/scripts/check-i18n-picker-completeness.mjs+++ b/scripts/check-i18n-picker-completeness.mjs@@ -158,6 +158,7 @@ function main() {console.error('');console.error(' Either finish the catalog, or take the locale out of PICKER_LOCALES');console.error(` in ${LOCALES_TS} until someone who reads it has reviewed it.`);+ console.error(' Review and promotion process: packages/app/src/locales/REVIEW.md');console.error(' Locked terminology: packages/app/src/locales/GLOSSARY.md');return 1;}diff --git a/scripts/generate-locale-review-packet.mjs b/scripts/generate-locale-review-packet.mjsnew file mode 100644index 000000000..9d4c1bfae--- /dev/null+++ b/scripts/generate-locale-review-packet.mjs@@ -0,0 +1,604 @@+#!/usr/bin/env node+/**+ * Build a self-contained review packet for one interface locale.+ *+ * A locale enters the Settings picker when someone who reads it has reviewed+ * it. Nothing here decides that; this produces the artifact the reviewer reads.+ * The output is a single Markdown file with no links into a checkout, so the+ * reviewer needs a text editor and nothing else — no clone, no install, no+ * running app. `packages/app/src/locales/REVIEW.md` is the process around it.+ *+ * The packet is a SAMPLE and says so. The catalogs hold ~2,900 messages per+ * locale; nobody reads 2,900 strings as a favour, and a review request that+ * asks for it gets declined or gets skimmed, which is worse than asking for+ * less. So the packet asks for roughly a hundred, chosen where a wrong answer+ * does the most damage.+ *+ * ## The selection rule+ *+ * Deterministic, so two runs on the same catalog produce the same packet and a+ * reviewer's numbered feedback still points at the same strings tomorrow.+ * Nothing here samples randomly or reads the clock.+ *+ * 1. **The glossary.** Every locked noun for this locale, whole. It is under+ * ten rows and it is the highest-leverage text in the project: CI enforces+ * whatever it pins across every message that uses the term, so a wrong+ * entry is not one bad string, it is the same bad string everywhere.+ * 2. **The glossary in use.** For each locked noun, up to+ * `MAX_PER_GLOSSARY_TERM` messages whose English contains it — shortest+ * English first, ties broken by message id. Shortest-first selects labels+ * and buttons over paragraphs, which is where a mistranslated noun is most+ * visible and least recoverable from context.+ * 3. **High-traffic chrome.** The surfaces in `CHROME_SURFACES`, filled+ * round-robin so no single surface eats the budget, each ordered+ * shortest-English-first and tie-broken by message id. Round-robin rather+ * than by volume: the menu bar has 60 messages and the language picker+ * has one, and the one matters more.+ *+ * No message is offered twice, whether it was already taken by step 2 or sits+ * on two surfaces at once — several menu labels also live in the command+ * palette.+ *+ * Usage:+ * node scripts/generate-locale-review-packet.mjs <locale> [--out <file>]+ *+ * With no `--out` the packet goes to stdout.+ */++import { existsSync, readFileSync, writeFileSync } from 'node:fs';+import { join } from 'node:path';+import { fileURLToPath } from 'node:url';+import {+ parsePoCatalog,+ requiredPluralCategories,+ SOURCE_LOCALE,+} from './check-i18n-new-string-translations.mjs';++const OK_ROOT = fileURLToPath(new URL('..', import.meta.url));+const LOCALES_TS = 'packages/core/src/i18n/locales.ts';+const GLOSSARY_MD = 'packages/app/src/locales/GLOSSARY.md';+const REVIEW_MD = 'packages/app/src/locales/REVIEW.md';+const CATALOG_REL = (locale) => `packages/app/src/locales/${locale}/messages.po`;++/** Roughly how many numbered strings the packet asks a reviewer to read. */+export const TARGET_MESSAGES = 100;++/** How many uses of one locked noun to show. Enough to see drift, not a corpus. */+export const MAX_PER_GLOSSARY_TERM = 3;++/**+ * The chrome a reader of this language meets before anything else, in the order+ * they meet it.+ *+ * Source paths rather than a heuristic, because "high traffic" is a product+ * judgement and a heuristic would quietly re-derive it wrong. A surface that+ * matches no messages is a hard error, not an empty section: it means a file+ * moved and the packet silently stopped covering a screen.+ */+export const CHROME_SURFACES = [+ {+ label: 'Preferences, where the language picker lives',+ why: 'The one screen a reader of this language is guaranteed to have visited, since it is where they chose the language.',+ files: [+ 'src/components/settings/LanguageSelect.tsx',+ 'src/components/settings/settings-fields.ts',+ 'src/components/settings/field-controls.tsx',+ ],+ },+ {+ label: 'Menu bar',+ why: 'Always on screen, and the vocabulary every other surface is read against.',+ files: ['src/lib/native-menu-catalog.ts', 'src/components/AppMenubar.tsx'],+ },+ {+ label: 'Command palette and keyboard shortcuts',+ why: 'The fastest path to every action in the app, so its labels are read more often than the buttons they duplicate.',+ files: [+ 'src/components/CommandPalette.tsx',+ 'src/components/command-palette-commands.ts',+ 'src/lib/keyboard-shortcuts.ts',+ ],+ },+ {+ label: 'Files and navigation',+ why: 'Permanently on screen beside the document, and where the glossary nouns for document and folder are load-bearing.',+ files: ['src/components/FileTree.tsx', 'src/components/FileSidebar.tsx'],+ },+ {+ label: 'Settings',+ why: 'Where a user goes when something is wrong, which is the worst moment to meet unclear copy.',+ files: ['src/components/settings/SettingsDialogShell.tsx'],+ },+];++/**+ * Pull a locale tuple out of core's TypeScript source by name.+ *+ * Read as text rather than imported: this runs as plain Node with no build step+ * and no TS loader. Parameterized where the two gate scripts each hard-code the+ * one tuple they gate, because a packet reports on all three at once — a+ * reviewer of a layout-deferred locale needs to be told their review cannot+ * promote it yet.+ */+export function readLocaleTuple(source, name) {+ const block = new RegExp(`export const ${name}\\s*=\\s*\\[([\\s\\S]*?)\\]`).exec(source);+ if (!block) {+ throw new Error(`Could not find a ${name} array in ${LOCALES_TS}`);+ }+ const tags = [...block[1].matchAll(/'([^']+)'/g)].map((m) => m[1]);+ if (tags.length === 0) {+ throw new Error(`${name} in ${LOCALES_TS} parsed as empty`);+ }+ return tags;+}++/**+ * Parse the catalog into entries that keep their source references.+ *+ * `parsePoCatalog` drops comment lines, and `#:` references are what say which+ * screen a message is on. Rather than fork its quoting and continuation+ * handling — the part that is fiddly and the part that must not drift — each+ * blank-line-separated block is handed to it whole and the references are+ * scavenged alongside. The header block keys on an empty msgid, which+ * `parsePoCatalog` already drops.+ */+export function parsePoEntries(text) {+ const entries = [];+ for (const block of text.split(/\n[ \t]*\n/)) {+ const parsed = parsePoCatalog(block);+ const [first] = [...parsed.entries()];+ if (!first) continue;+ const [id, str] = first;+ const references = [];+ for (const line of block.split('\n')) {+ const ref = /^#:\s*(.+)$/.exec(line.trim());+ if (ref) references.push(...ref[1].trim().split(/\s+/));+ }+ entries.push({ id, str, references });+ }+ return entries;+}++/**+ * The locked nouns for one locale, read out of the glossary's own tables.+ *+ * The glossary splits its rows across several tables so the columns stay+ * readable; which table a locale sits in is a formatting decision, so this+ * looks for the column by header rather than by position.+ */+export function readGlossaryTerms(markdown, locale) {+ const terms = [];+ let headers = null;+ let column = -1;++ for (const raw of markdown.split('\n')) {+ const line = raw.trim();+ if (!line.startsWith('|')) {+ headers = null;+ column = -1;+ continue;+ }+ const cells = line+ .slice(1, line.endsWith('|') ? -1 : undefined)+ .split('|')+ .map((cell) => cell.trim());+ if (!headers) {+ headers = cells.map((cell) => cell.replace(/`/g, ''));+ column = headers.indexOf(locale);+ continue;+ }+ // The `| --- | --- |` separator under every header row.+ if (cells.every((cell) => /^:?-{3,}:?$/.test(cell))) continue;+ if (column > 0 && cells[column]) {+ terms.push({ term: cells[0], translation: cells[column] });+ }+ }+ return terms;+}++/** The verbatim body of one `##` section, for quoting into the packet. */+export function readSection(markdown, heading) {+ const lines = markdown.split('\n');+ const start = lines.findIndex((line) => line.trim() === `## ${heading}`);+ if (start === -1) return '';+ const rest = lines.slice(start + 1);+ const end = rest.findIndex((line) => /^##\s/.test(line));+ return (end === -1 ? rest : rest.slice(0, end)).join('\n').trim();+}++/**+ * The per-locale review state, read out of `REVIEW.md`'s tracking table.+ *+ * Parsed rather than trusted as prose so the table cannot quietly fall out of+ * step with the catalogs it tracks: a locale with no row here has no packet.+ */+export function readReviewStatus(markdown) {+ const rows = new Map();+ for (const raw of markdown.split('\n')) {+ const line = raw.trim();+ const match = /^\|\s*`([^`]+)`\s*\|(.*)\|?$/.exec(line);+ if (!match) continue;+ const cells = match[2].split('|').map((cell) => cell.trim());+ const [language, status, basis, evidence, blocker] = cells;+ rows.set(match[1], {+ language: language ?? '',+ status: (status ?? '').toLowerCase(),+ basis: basis ?? '',+ evidence: evidence ?? '',+ blocker: blocker ?? '',+ });+ }+ return rows;+}++/** A locked noun, its plural, and neither one wearing another word's tail. */+function termPattern(term) {+ const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');+ return new RegExp(`(?<!\\p{L})${escaped}s?(?!\\p{L})`, 'iu');+}++/**+ * Shortest English first, ties broken by message id.+ *+ * Length is a proxy for how much surrounding context a reader gets: a+ * three-word button carries its meaning alone and a paragraph explains itself,+ * so the short ones are where a wrong word does the damage.+ */+function byLeverage(a, b) {+ const lengthDelta = (a.source ?? '').length - (b.source ?? '').length;+ return lengthDelta !== 0 ? lengthDelta : a.id < b.id ? -1 : a.id > b.id ? 1 : 0;+}++/**+ * Apply the selection rule to a parsed catalog pair.+ *+ * Returns `{ glossaryUses, surfaces }`, both already deduplicated and ordered.+ * Split out from the formatting so the rule can be tested without reading a+ * hundred lines of Markdown.+ */+export function selectMessages({+ entries,+ translations,+ glossaryTerms,+ surfaces = CHROME_SURFACES,+ target = TARGET_MESSAGES,+ maxPerTerm = MAX_PER_GLOSSARY_TERM,+}) {+ const candidates = entries.map((entry) => ({+ id: entry.id,+ source: entry.str || entry.id,+ translation: translations.get(entry.id) ?? '',+ references: entry.references,+ }));+ const chosen = new Set();++ const glossaryUses = [];+ for (const { term, translation } of glossaryTerms) {+ const pattern = termPattern(term);+ const uses = candidates+ .filter((candidate) => !chosen.has(candidate.id) && pattern.test(candidate.source))+ .sort(byLeverage)+ .slice(0, maxPerTerm);+ for (const use of uses) chosen.add(use.id);+ glossaryUses.push({ term, translation, uses });+ }++ const queues = surfaces.map((surface) => ({+ surface,+ remaining: candidates+ .filter(+ (candidate) =>+ !chosen.has(candidate.id) &&+ candidate.references.some((ref) => surface.files.includes(ref)),+ )+ .sort(byLeverage),+ picked: [],+ }));++ let budget = Math.max(0, target - chosen.size);+ let progressed = true;+ while (budget > 0 && progressed) {+ progressed = false;+ for (const queue of queues) {+ if (budget === 0) break;+ // A message can be referenced from more than one surface — "Back" and+ // "View" sit in both the menu bar and the command palette — so it can be+ // in two queues at once. Re-check at the point of picking rather than+ // only when the queues were built, or the packet offers the same string+ // twice under two numbers and the reviewer reads it twice.+ let next = queue.remaining.shift();+ while (next && chosen.has(next.id)) next = queue.remaining.shift();+ if (!next) continue;+ queue.picked.push(next);+ chosen.add(next.id);+ budget--;+ progressed = true;+ }+ }++ return {+ glossaryUses,+ surfaces: queues.map(({ surface, picked }) => ({ surface, messages: picked })),+ };+}++/** Message text on one line, so a multi-line string cannot break the list. */+const oneLine = (text) => text.replace(/\r?\n/g, ' ⏎ ').trim();++function renderMessage(number, locale, message) {+ return [+ `**${number}.**`,+ `- \`en\` — ${oneLine(message.source)}`,+ `- \`${locale}\` — ${oneLine(message.translation) || '_(empty — nothing to review here yet)_'}`,+ ].join('\n');+}++/** The locale's name in its own language, which is how the reviewer knows it. */+function endonym(locale) {+ try {+ return new Intl.DisplayNames([locale], { type: 'language' }).of(locale) ?? locale;+ } catch {+ return locale;+ }+}++/**+ * What approving this packet actually changes, which is not the same question+ * for all three kinds of locale.+ *+ * An already-offered locale is the awkward case and the one worth being+ * straight about: the review does not add it to anything, it replaces an+ * assumption with a fact. A reviewer told "you are deciding whether to ship+ * this" about a language that already shipped will notice.+ */+function stakes({ offered, promotable }) {+ if (offered) {+ return '- **If you approve:** nothing changes on screen — the language is already offered. What changes is that it is offered because someone read it, rather than because nobody had reason to doubt it. If you do not approve, we take it out of the picker.';+ }+ if (promotable) {+ return '- **If you approve:** the language is added to the in-app language picker and users can select it.';+ }+ return '- **If you approve:** the catalog is marked reviewed, but the language still will not appear in the picker yet. Its right-to-left layout is unfinished, and offering a language the app lays out wrongly is not something a translation can fix. Your review is what makes it ready for the moment that work lands, and it is not wasted — but you should know it before spending the hour.';+}++export function buildPacket({+ locale,+ status,+ offered,+ promotable,+ catalogStamp,+ messageCount,+ glossaryTerms,+ neverTranslated,+ selection,+}) {+ const lines = [];+ const push = (...text) => lines.push(...text, '');+ let number = 0;++ const name = endonym(locale);+ push(`# Reviewing OpenKnowledge in ${name} (\`${locale}\`)`);+ push(+ offered+ ? [+ `OpenKnowledge's interface has been translated into ${name} by a coding agent working against`,+ 'a locked vocabulary, and the app already offers the language. What it has never had is a',+ 'reader: nobody who reads it has checked whether the words are right. You are being asked to',+ 'read a sample and say whether it is good enough to keep offering.',+ ].join('\n')+ : [+ `OpenKnowledge's interface has been translated into ${name} by a coding agent working against`,+ 'a locked vocabulary. Nobody who reads the language has read it yet, which is why the language',+ "is not offered in the app's language picker. You are being asked to read a sample of it and",+ 'say whether it is fit to offer.',+ ].join('\n'),+ );+ push(+ 'You do not need the app, a checkout, or any tooling. Everything you need is in this file.',+ 'It should take under an hour.',+ );++ push('## What we are asking');+ push(+ '1. Read section 1, the locked vocabulary. It is under ten words and it matters more than',+ ' everything else here put together, because each one is enforced across every message',+ ' that uses it.',+ '2. Skim sections 2 and 3. Each string is numbered.',+ '3. Send back the numbers you would change and what they should say. Prose is fine; a list',+ ' of `17 → <better wording>` is ideal. "The rest reads fine" is a real and useful answer.',+ );+ push(+ 'Judge it as a native reader of software, not as a translator grading a translation. The',+ 'question is whether someone using the app in this language would trust it, not whether',+ 'each line is the best possible rendering.',+ );++ push('## Before you start');+ push(+ `- **Current state:** ${status.status || 'unknown'}${status.basis && status.basis !== '—' ? ` — ${status.basis}` : ''}.`,+ `- **Catalog:** ${messageCount} messages, extracted ${catalogStamp}. This packet samples about ${TARGET_MESSAGES} of them; the rule is at the bottom.`,+ `- **Plural forms this language needs:** ${requiredPluralCategories(locale).join(', ')}.`,+ stakes({ offered, promotable }),+ );+ push(+ 'Placeholders like `{name}`, `{count}` and `#` are substituted at runtime. They must survive',+ 'unchanged and untranslated; word order around them can move freely. `⏎` marks a line break',+ 'inside a message.',+ );++ push('## 1. The locked vocabulary');+ push(+ 'These words are pinned. Every message that mentions the concept uses the pinned form, and',+ 'CI enforces it. A wrong entry here is the single most expensive kind of mistake in this',+ 'catalog, and the cheapest to catch — so read this table twice and the rest once.',+ );+ push(+ `| Concept (English) | Current \`${locale}\` |`,+ '| --- | --- |',+ ...glossaryTerms.map(({ term, translation }) => `| ${term} | ${translation} |`),+ );+ if (neverTranslated) {+ push('### These are deliberately never translated', neverTranslated);+ }++ push('## 2. The vocabulary in use');+ push(+ 'The same words in real messages. Terminology drift is invisible to every automated check —',+ 'a catalog that renders one concept three different ways is still complete and still passes',+ 'CI — so this is the section only you can review.',+ );+ for (const { term, translation, uses } of selection.glossaryUses) {+ push(`### ${term} → ${translation}`);+ if (uses.length === 0) {+ // A pinned word no message uses yet. Said out loud rather than skipped:+ // silence would read as "reviewed in context" when nothing was.+ push(+ 'No interface message uses this word today, so there is nothing to read it in context.',+ 'Judge the table entry above on its own.',+ );+ continue;+ }+ for (const message of uses) {+ number += 1;+ push(renderMessage(number, locale, message));+ }+ }++ push('## 3. The interface');+ push('The surfaces a user meets most often, in the order they meet them.');+ for (const { surface, messages } of selection.surfaces) {+ if (messages.length === 0) continue;+ push(`### ${surface.label}`, `_${surface.why}_`);+ for (const message of messages) {+ number += 1;+ push(renderMessage(number, locale, message));+ }+ }++ push('## How this sample was chosen');+ push(+ `${number} strings out of ${messageCount}, chosen by a fixed rule rather than at random, so`,+ 'the same numbers mean the same strings if we send you an updated packet:',+ '',+ '1. Every locked vocabulary word.',+ `2. Up to ${MAX_PER_GLOSSARY_TERM} messages using each of those words, shortest first.`,+ '3. The interface surfaces above, filled evenly between them, shortest first.',+ );+ push(+ 'Shortest first on purpose: a short label carries its meaning alone, while a paragraph',+ 'explains itself even when a word inside it is off. The short ones are where a wrong word',+ 'does the most damage.',+ );+ push(+ 'What this sample cannot tell us is whether the other ~2,800 messages are good. It tells us',+ 'whether the vocabulary and the surfaces people actually live in are good, which is the part',+ "worth an hour of a native reader's time. If this sample reads badly, that is a strong",+ 'signal about the whole catalog.',+ );++ return `${lines+ .join('\n')+ .replace(/\n{3,}/g, '\n\n')+ .trim()}\n`;+}++export function generate({ locale, root = OK_ROOT }) {+ const localesSource = readFileSync(join(root, LOCALES_TS), 'utf8');+ const supported = readLocaleTuple(localesSource, 'SUPPORTED_LOCALES');+ const picker = readLocaleTuple(localesSource, 'PICKER_LOCALES');+ const layoutDeferred = readLocaleTuple(localesSource, 'LAYOUT_DEFERRED_LOCALES');++ if (!supported.includes(locale)) {+ throw new Error(+ `${locale} is not an enumerated locale. ${LOCALES_TS} lists: ${supported.join(', ')}`,+ );+ }+ if (locale === SOURCE_LOCALE) {+ throw new Error(+ `${SOURCE_LOCALE} is the source catalog — its translation is the English text itself, so there is nothing to review.`,+ );+ }++ const reviewStatus = readReviewStatus(readFileSync(join(root, REVIEW_MD), 'utf8'));+ const status = reviewStatus.get(locale);+ if (!status) {+ throw new Error(+ `${locale} has no row in ${REVIEW_MD}. Add one before generating a packet — an untracked review is a review nobody can find again.`,+ );+ }++ const catalogPath = join(root, CATALOG_REL(locale));+ if (!existsSync(catalogPath)) {+ throw new Error(`No catalog at ${CATALOG_REL(locale)}`);+ }++ const sourceText = readFileSync(join(root, CATALOG_REL(SOURCE_LOCALE)), 'utf8');+ const entries = parsePoEntries(sourceText);+ const translations = parsePoCatalog(readFileSync(catalogPath, 'utf8'));++ const glossary = readFileSync(join(root, GLOSSARY_MD), 'utf8');+ const glossaryTerms = readGlossaryTerms(glossary, locale);+ if (glossaryTerms.length === 0) {+ throw new Error(`${GLOSSARY_MD} has no column for ${locale}`);+ }++ const selection = selectMessages({ entries, translations, glossaryTerms });++ const stamp = /POT-Creation-Date:\s*([^\\\n"]+)/.exec(sourceText);+ return buildPacket({+ locale,+ status,+ offered: picker.includes(locale),+ promotable: !layoutDeferred.includes(locale),+ catalogStamp: stamp ? stamp[1].trim() : 'an unrecorded date',+ messageCount: entries.length,+ glossaryTerms,+ neverTranslated: readSection(glossary, 'Never translated'),+ selection,+ });+}++export function parseArgs(argv) {+ let out = null;+ let locale = null;+ for (let i = 0; i < argv.length; i++) {+ if (argv[i] === '--out') {+ out = argv[++i] ?? null;+ } else if (!argv[i].startsWith('--') && locale === null) {+ locale = argv[i];+ }+ }+ return { locale, out };+}++function main(argv) {+ const { locale, out } = parseArgs(argv);++ if (!locale) {+ console.error('Usage: node scripts/generate-locale-review-packet.mjs <locale> [--out <file>]');+ console.error('');+ console.error(' Builds the review packet a native speaker reads before a locale can be');+ console.error(` offered in the language picker. Process: ${REVIEW_MD}`);+ return 1;+ }++ let packet;+ try {+ packet = generate({ locale });+ } catch (error) {+ console.error(`ERROR: ${error.message}`);+ return 1;+ }++ if (out) {+ writeFileSync(out, packet);+ console.log(`Wrote the ${locale} review packet to ${out}`);+ } else {+ process.stdout.write(packet);+ }+ return 0;+}++if (import.meta.url === `file://${process.argv[1]}`) {+ process.exit(main(process.argv.slice(2)));+}diff --git a/scripts/generate-locale-review-packet.test.mjs b/scripts/generate-locale-review-packet.test.mjsnew file mode 100644index 000000000..cadfd3c49--- /dev/null+++ b/scripts/generate-locale-review-packet.test.mjs@@ -0,0 +1,565 @@+import { spawnSync } from 'node:child_process';+import { readFileSync } from 'node:fs';+import { join } from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, test } from 'vitest';+import {+ buildPacket,+ CHROME_SURFACES,+ generate,+ MAX_PER_GLOSSARY_TERM,+ parseArgs,+ parsePoEntries,+ readGlossaryTerms,+ readLocaleTuple,+ readReviewStatus,+ readSection,+ selectMessages,+ TARGET_MESSAGES,+} from './generate-locale-review-packet.mjs';++const OK_ROOT = fileURLToPath(new URL('..', import.meta.url));+const read = (rel) => readFileSync(join(OK_ROOT, rel), 'utf8');++const LOCALES_TS = read('packages/core/src/i18n/locales.ts');+const REVIEW_MD = read('packages/app/src/locales/REVIEW.md');+const SOURCE_CATALOG = read('packages/app/src/locales/en/messages.po');++const SUPPORTED = readLocaleTuple(LOCALES_TS, 'SUPPORTED_LOCALES');+const PICKER = readLocaleTuple(LOCALES_TS, 'PICKER_LOCALES');+const LAYOUT_DEFERRED = readLocaleTuple(LOCALES_TS, 'LAYOUT_DEFERRED_LOCALES');++describe('reading the locale tuples', () => {+ test('reads each tuple out of core by name', () => {+ expect(SUPPORTED).toContain('en');+ expect(PICKER.every((locale) => SUPPORTED.includes(locale))).toBe(true);+ expect(LAYOUT_DEFERRED.every((locale) => SUPPORTED.includes(locale))).toBe(true);+ });++ test('refuses a source it cannot find the named tuple in', () => {+ expect(() =>+ readLocaleTuple("export const SUPPORTED_LOCALES = ['en'];", 'PICKER_LOCALES'),+ ).toThrow(/PICKER_LOCALES/);+ });++ test('refuses an empty tuple rather than reporting nothing to promote', () => {+ expect(() =>+ readLocaleTuple('export const PICKER_LOCALES = [] as const;', 'PICKER_LOCALES'),+ ).toThrow(/empty/);+ });+});++describe('parsing the catalog with its source references', () => {+ const catalog = [+ 'msgid ""',+ 'msgstr ""',+ '"Language: en\\n"',+ '',+ '#: src/components/Alpha.tsx',+ 'msgid "Save"',+ 'msgstr "Save"',+ '',+ '#. placeholder {0}: name',+ '#: src/components/Alpha.tsx',+ '#: src/components/Beta.tsx',+ 'msgid "Delete {0}?"',+ 'msgstr "Delete {0}?"',+ '',+ ].join('\n');++ test('keeps the source references a plain catalog parse discards', () => {+ expect(parsePoEntries(catalog)).toEqual([+ { id: 'Save', str: 'Save', references: ['src/components/Alpha.tsx'] },+ {+ id: 'Delete {0}?',+ str: 'Delete {0}?',+ references: ['src/components/Alpha.tsx', 'src/components/Beta.tsx'],+ },+ ]);+ });++ test('drops the header block, which carries metadata rather than a message', () => {+ expect(parsePoEntries(catalog).map((entry) => entry.id)).not.toContain('');+ });++ test('reads a message whose text is wrapped across continuation lines', () => {+ const wrapped = ['#: src/a.tsx', 'msgid ""', '"one "', '"two"', 'msgstr ""', '"uno dos"'].join(+ '\n',+ );+ expect(parsePoEntries(wrapped)).toEqual([+ { id: 'one two', str: 'uno dos', references: ['src/a.tsx'] },+ ]);+ });+});++describe('reading the glossary', () => {+ const glossary = [+ '## The nouns',+ '',+ '| Term | `es` | `fr` |',+ '| --- | --- | --- |',+ '| document | documento | document |',+ '| folder | carpeta | dossier |',+ '',+ '| Term | `hi` |',+ '| --- | --- |',+ '| document | दस्तावेज़ |',+ '',+ '## Never translated',+ '',+ '- **OpenKnowledge** — the product name.',+ '',+ '## Why these forms',+ '',+ 'Because.',+ ].join('\n');++ test('finds a locale column by its header rather than its position', () => {+ expect(readGlossaryTerms(glossary, 'fr')).toEqual([+ { term: 'document', translation: 'document' },+ { term: 'folder', translation: 'dossier' },+ ]);+ });++ // The glossary splits rows across several tables so the columns stay readable.+ // Which table a locale sits in is formatting, and must not change what it holds.+ test('reads a locale that sits in a later table', () => {+ expect(readGlossaryTerms(glossary, 'hi')).toEqual([+ { term: 'document', translation: 'दस्तावेज़' },+ ]);+ });++ test('returns nothing for a locale the glossary has no column for', () => {+ expect(readGlossaryTerms(glossary, 'sv')).toEqual([]);+ });++ test('quotes one section verbatim and stops at the next heading', () => {+ expect(readSection(glossary, 'Never translated')).toBe(+ '- **OpenKnowledge** — the product name.',+ );+ });+});++describe('the selection rule', () => {+ const surfaces = [+ { label: 'Alpha', why: 'first', files: ['src/Alpha.tsx'] },+ { label: 'Beta', why: 'second', files: ['src/Beta.tsx'] },+ ];+ const entry = (id, references) => ({ id, str: id, references });++ test('shows each locked word in context, shortest English first', () => {+ const { glossaryUses } = selectMessages({+ entries: [+ entry('Delete this document permanently?', []),+ entry('New document', []),+ entry('Document', []),+ ],+ translations: new Map(),+ glossaryTerms: [{ term: 'document', translation: 'documento' }],+ surfaces,+ maxPerTerm: 2,+ });+ expect(glossaryUses[0].uses.map((use) => use.id)).toEqual(['Document', 'New document']);+ });++ // `document` appears in hundreds of messages. Without the cap it alone would+ // spend the whole budget and the reviewer would never reach the interface.+ test('caps how many uses of one locked word it shows', () => {+ const { glossaryUses } = selectMessages({+ entries: Array.from({ length: 20 }, (_, i) => entry(`document ${'x'.repeat(i)}`, [])),+ translations: new Map(),+ glossaryTerms: [{ term: 'document', translation: 'documento' }],+ surfaces,+ });+ expect(glossaryUses[0].uses.length).toBe(MAX_PER_GLOSSARY_TERM);+ });++ test('matches a locked word case-insensitively and in the plural', () => {+ const { glossaryUses } = selectMessages({+ entries: [entry('All folders', []), entry('a FOLDER', [])],+ translations: new Map(),+ glossaryTerms: [{ term: 'folder', translation: 'carpeta' }],+ surfaces,+ });+ expect(glossaryUses[0].uses.map((use) => use.id).sort()).toEqual(['All folders', 'a FOLDER']);+ });++ // "branch" must not match "branching" — a pinned noun and a word that merely+ // starts with it are different reviews.+ test("does not match a locked word wearing another word's tail", () => {+ const { glossaryUses } = selectMessages({+ entries: [entry('Branching strategy', []), entry('Rebranch', [])],+ translations: new Map(),+ glossaryTerms: [{ term: 'branch', translation: 'rama' }],+ surfaces,+ });+ expect(glossaryUses[0].uses).toEqual([]);+ });++ test('fills the surfaces round-robin so a large one cannot crowd out a small one', () => {+ const { surfaces: picked } = selectMessages({+ entries: [+ entry('a1', ['src/Alpha.tsx']),+ entry('a2', ['src/Alpha.tsx']),+ entry('a3', ['src/Alpha.tsx']),+ entry('a4', ['src/Alpha.tsx']),+ entry('b1', ['src/Beta.tsx']),+ entry('b2', ['src/Beta.tsx']),+ ],+ translations: new Map(),+ glossaryTerms: [],+ surfaces,+ target: 4,+ });+ expect(picked.map(({ messages }) => messages.map((m) => m.id))).toEqual([+ ['a1', 'a2'],+ ['b1', 'b2'],+ ]);+ });++ test('keeps filling from the surfaces that still have messages once one runs dry', () => {+ const { surfaces: picked } = selectMessages({+ entries: [+ entry('a1', ['src/Alpha.tsx']),+ entry('b1', ['src/Beta.tsx']),+ entry('b2', ['src/Beta.tsx']),+ entry('b3', ['src/Beta.tsx']),+ ],+ translations: new Map(),+ glossaryTerms: [],+ surfaces,+ target: 4,+ });+ expect(picked.map(({ messages }) => messages.length)).toEqual([1, 3]);+ });++ // "Back" and "View" really are referenced from both the menu bar and the+ // command palette, so this is the shape the packet hits, not a hypothetical.+ test('does not offer a message twice when two surfaces both reference it', () => {+ const { surfaces: picked } = selectMessages({+ entries: [+ entry('shared', ['src/Alpha.tsx', 'src/Beta.tsx']),+ entry('b-only', ['src/Beta.tsx']),+ ],+ translations: new Map(),+ glossaryTerms: [],+ surfaces,+ target: 10,+ });+ expect(picked.map(({ messages }) => messages.map((m) => m.id))).toEqual([+ ['shared'],+ ['b-only'],+ ]);+ });++ test('does not offer a message twice when a surface also uses a locked word', () => {+ const { glossaryUses, surfaces: picked } = selectMessages({+ entries: [entry('New folder', ['src/Alpha.tsx']), entry('a2', ['src/Alpha.tsx'])],+ translations: new Map(),+ glossaryTerms: [{ term: 'folder', translation: 'carpeta' }],+ surfaces,+ target: 10,+ });+ expect(glossaryUses[0].uses.map((use) => use.id)).toEqual(['New folder']);+ expect(picked[0].messages.map((m) => m.id)).toEqual(['a2']);+ });++ test('carries the translation alongside the English, and marks an empty one', () => {+ const { surfaces: picked } = selectMessages({+ entries: [entry('Save', ['src/Alpha.tsx']), entry('Cancel', ['src/Alpha.tsx'])],+ translations: new Map([['Save', 'Guardar']]),+ glossaryTerms: [],+ surfaces,+ target: 2,+ });+ expect(picked[0].messages).toMatchObject([+ { id: 'Save', translation: 'Guardar' },+ { id: 'Cancel', translation: '' },+ ]);+ });+});++describe('the packet', () => {+ const packetFor = (overrides = {}) =>+ buildPacket({+ locale: 'fr',+ status: { status: 'unreviewed', basis: '—' },+ offered: false,+ promotable: true,+ catalogStamp: '2026-01-01',+ messageCount: 2900,+ glossaryTerms: [{ term: 'folder', translation: 'dossier' }],+ neverTranslated: '- **OpenKnowledge** — the product name.',+ selection: {+ glossaryUses: [+ {+ term: 'folder',+ translation: 'dossier',+ uses: [{ id: 'New folder', source: 'New folder', translation: 'Nouveau dossier' }],+ },+ ],+ surfaces: [+ {+ surface: CHROME_SURFACES[0],+ messages: [{ id: 'Save', source: 'Save', translation: 'Enregistrer' }],+ },+ ],+ },+ ...overrides,+ });++ test('names the language in the language, so its reader recognises it', () => {+ expect(packetFor()).toMatch(/français/);+ });++ test('shows the English and the translation together for every numbered string', () => {+ const packet = packetFor();+ expect(packet).toMatch(/\*\*1\.\*\*\n- `en` — New folder\n- `fr` — Nouveau dossier/);+ expect(packet).toMatch(/\*\*2\.\*\*\n- `en` — Save\n- `fr` — Enregistrer/);+ });++ test('numbers run continuously across the glossary and the interface sections', () => {+ const numbers = [...packetFor().matchAll(/^\*\*(\d+)\.\*\*$/gm)].map((m) => Number(m[1]));+ expect(numbers).toEqual([1, 2]);+ });++ // A reviewer of a right-to-left locale is spending an hour on something that+ // cannot promote their language yet. Telling them up front is the only honest+ // way to ask.+ test('tells a reviewer up front when approving will not promote the locale', () => {+ expect(packetFor({ promotable: false })).toMatch(/will not appear in the picker yet/);+ expect(packetFor({ promotable: true })).not.toMatch(/will not appear in the picker yet/);+ });++ // Two of the three offered locales have never been read. A packet that tells+ // their reviewer they are deciding whether to ship a language that already+ // shipped reads as a form letter, and gets treated as one.+ test('does not tell a reviewer of an already-offered locale that it is unoffered', () => {+ const packet = packetFor({ offered: true });+ expect(packet).toMatch(/the app already offers the language/);+ expect(packet).toMatch(/nothing changes on screen/);+ expect(packet).not.toMatch(/is not offered in the app's language picker/);+ });++ test('tells a reviewer of an unoffered locale that approving adds it', () => {+ const packet = packetFor({ offered: false });+ expect(packet).toMatch(/is not offered in the app's language picker/);+ expect(packet).toMatch(/the language is added to the in-app language picker/);+ });++ test('says a locked word has no uses rather than silently omitting it', () => {+ const packet = packetFor({+ selection: {+ glossaryUses: [{ term: 'checkpoint', translation: 'point de contrôle', uses: [] }],+ surfaces: [],+ },+ });+ expect(packet).toMatch(/checkpoint → point de contrôle/);+ expect(packet).toMatch(/No interface message uses this word today/);+ });++ test('states the selection rule, so the sample is not mistaken for the whole catalog', () => {+ const packet = packetFor();+ expect(packet).toMatch(/How this sample was chosen/);+ expect(packet).toMatch(/2 strings out of 2900/);+ });++ test('folds a multi-line message onto one line so the list cannot break', () => {+ const packet = packetFor({+ selection: {+ glossaryUses: [],+ surfaces: [+ {+ surface: CHROME_SURFACES[0],+ messages: [{ id: 'a', source: 'one\ntwo', translation: 'un\ndeux' }],+ },+ ],+ },+ });+ expect(packet).toMatch(/- `en` — one ⏎ two/);+ expect(packet).toMatch(/- `fr` — un ⏎ deux/);+ });+});++describe('the command line', () => {+ test('takes the locale positionally, with or without an output file', () => {+ expect(parseArgs(['fr'])).toEqual({ locale: 'fr', out: null });+ expect(parseArgs(['fr', '--out', '/tmp/fr.md'])).toEqual({ locale: 'fr', out: '/tmp/fr.md' });+ });++ // `--out fr` would otherwise read its own filename as the locale.+ test('does not mistake the output path for the locale when the flag comes first', () => {+ expect(parseArgs(['--out', '/tmp/fr.md', 'fr'])).toEqual({ locale: 'fr', out: '/tmp/fr.md' });+ });++ test('reports no locale rather than guessing one', () => {+ expect(parseArgs([])).toEqual({ locale: null, out: null });+ expect(parseArgs(['--out', '/tmp/fr.md'])).toMatchObject({ locale: null });+ });+});++describe('the tracking table', () => {+ const status = readReviewStatus(REVIEW_MD);++ test('parses a row into its recorded fields', () => {+ expect(+ readReviewStatus(+ '| `fr` | français | reviewed | A. Reviewer | inkeep/open-knowledge#42 | — |',+ ),+ ).toEqual(+ new Map([+ [+ 'fr',+ {+ language: 'français',+ status: 'reviewed',+ basis: 'A. Reviewer',+ evidence: 'inkeep/open-knowledge#42',+ blocker: '—',+ },+ ],+ ]),+ );+ });++ test('ignores the header separator and any prose around the table', () => {+ expect(readReviewStatus('| Locale | Language |\n| --- | --- |\nnot a row').size).toBe(0);+ });++ test('records every enumerated locale', () => {+ expect(SUPPORTED.filter((locale) => !status.has(locale))).toEqual([]);+ });++ test('uses only the four defined statuses', () => {+ const undefined_ = [...status.entries()]+ .filter(([, row]) => !['source', 'reviewed', 'vouched', 'unreviewed'].includes(row.status))+ .map(([locale, row]) => `${locale}: ${row.status}`);+ expect(undefined_).toEqual([]);+ });++ // The whole point of the record: nothing is offered on an unstated basis. Two+ // of the three current entries are `vouched` rather than `reviewed`, which is+ // the honest reading of how they got there.+ test('every locale the picker offers has its basis on the record', () => {+ const unaccounted = PICKER.filter(+ (locale) => !['source', 'reviewed', 'vouched'].includes(status.get(locale)?.status),+ );+ expect(unaccounted).toEqual([]);+ });++ test('every offered locale but the source states why it is offered', () => {+ const unexplained = PICKER.filter((locale) => locale !== 'en').filter((locale) => {+ const evidence = status.get(locale)?.evidence;+ return !evidence || evidence === '—';+ });+ expect(unexplained).toEqual([]);+ });++ // `vouched` records how the v1 picker got its entries. It is not a status to+ // hand out — a locale outside the picker has no v1 grandfathering to record.+ test('nothing outside the picker is marked vouched', () => {+ const spurious = [...status.entries()]+ .filter(([locale, row]) => row.status === 'vouched' && !PICKER.includes(locale))+ .map(([locale]) => locale);+ expect(spurious).toEqual([]);+ });++ test('the locales whose layout is unfinished are recorded as blocked', () => {+ const unmarked = LAYOUT_DEFERRED.filter((locale) => {+ const blocker = status.get(locale)?.blocker;+ return !blocker || blocker === '—';+ });+ expect(unmarked).toEqual([]);+ });++ test('no other locale carries a blocker it does not have', () => {+ const spurious = [...status.entries()]+ .filter(([locale]) => !LAYOUT_DEFERRED.includes(locale))+ .filter(([, row]) => row.blocker && row.blocker !== '—')+ .map(([locale]) => locale);+ expect(spurious).toEqual([]);+ });++ // A blocked locale cannot be offered however good its catalog is, so it must+ // not be in the picker even if someone reviews it.+ test('no blocked locale is offered in the picker', () => {+ expect(PICKER.filter((locale) => LAYOUT_DEFERRED.includes(locale))).toEqual([]);+ });+});++describe('against the real catalogs', () => {+ const entries = parsePoEntries(SOURCE_CATALOG);++ test.each(+ CHROME_SURFACES.map((surface) => [surface.label, surface]),+ )('the %s surface still matches messages in the catalog', (_label, surface) => {+ const matched = entries.filter((entry) =>+ entry.references.some((ref) => surface.files.includes(ref)),+ );+ expect(matched.length).toBeGreaterThan(0);+ });++ test.each(+ CHROME_SURFACES.flatMap((surface) => surface.files.map((file) => [file])),+ )('%s is still a source of user-facing messages', (file) => {+ expect(entries.some((entry) => entry.references.includes(file))).toBe(true);+ });++ test('builds a packet for every locale but the source', () => {+ for (const locale of SUPPORTED.filter((tag) => tag !== 'en')) {+ const packet = generate({ locale });+ expect(packet, locale).toMatch(/## 1\. The locked vocabulary/);+ expect(packet, locale).toMatch(/## How this sample was chosen/);+ }+ });++ // The two `vouched` picker entries are the ones most worth sending out, so+ // their packets must read correctly rather than being an afterthought.+ test('a packet for an offered locale reads as a check on what already ships', () => {+ for (const locale of PICKER.filter((tag) => tag !== 'en')) {+ expect(generate({ locale }), locale).toMatch(/the app already offers the language/);+ }+ });++ test('asks for about the number of strings it promises, not the whole catalog', () => {+ const numbers = [...generate({ locale: 'fr' }).matchAll(/^\*\*(\d+)\.\*\*$/gm)];+ expect(numbers.length).toBeGreaterThan(TARGET_MESSAGES * 0.75);+ expect(numbers.length).toBeLessThanOrEqual(TARGET_MESSAGES);+ });++ // Feedback arrives as "17 → …", so the same run must produce the same 17.+ test('is byte-identical across runs, so numbered feedback keeps pointing at the same string', () => {+ expect(generate({ locale: 'hi' })).toBe(generate({ locale: 'hi' }));+ });++ test('never asks a reviewer to read the same string twice', () => {+ const shown = [...generate({ locale: 'fr' }).matchAll(/^- `en` — (.*)$/gm)].map((m) => m[1]);+ expect(shown.length).toBe(new Set(shown).size);+ });++ test('refuses the source locale, which has nothing to review', () => {+ expect(() => generate({ locale: 'en' })).toThrow(/nothing to review/);+ });++ test('refuses a locale the app does not enumerate', () => {+ expect(() => generate({ locale: 'sv' })).toThrow(/not an enumerated locale/);+ });++ test('runs from the command line', () => {+ const result = spawnSync('node', ['scripts/generate-locale-review-packet.mjs', 'bn'], {+ cwd: OK_ROOT,+ encoding: 'utf8',+ });+ expect(result.status).toBe(0);+ expect(result.stdout).toMatch(/# Reviewing OpenKnowledge in/);+ });++ test('explains itself rather than throwing a stack trace when given no locale', () => {+ const result = spawnSync('node', ['scripts/generate-locale-review-packet.mjs'], {+ cwd: OK_ROOT,+ encoding: 'utf8',+ });+ expect(result.status).toBe(1);+ expect(result.stderr).toMatch(/Usage:/);+ });+});