@surea11y/core 1.4.0 → 1.5.0

package/docs/I18N.md

@@ -4,14 +4,18 @@ Every rule's title/description, and every occurrence's summary/hint, is localize
 
 ## Current locale coverage
 
-| Locale | File | Keys | Coverage vs. English |
+| Locale | File | Keys | Values still in English |
 |---|---|---|---|
-| `en` (English) | `src/i18n/en.js` | 614 | 100% (the canonical/fallback set) |
-| `fr` (French) | `src/i18n/fr.js` | 614 | 100% |
-| `de` (German) | `src/i18n/de.js` | 614 | 100% |
-| `es` (Spanish) | `src/i18n/es.js` | 614 | 100% |
+| `en` (English) | `src/i18n/en.json` | 633 | — (the canonical/fallback set) |
+| `fr` (French) | `src/i18n/fr.json` | 633 | 1 |
+| `de` (German) | `src/i18n/de.json` | 633 | 0 |
+| `es` (Spanish) | `src/i18n/es.json` | 633 | 0 |
 
-All four locales are fully translated as of this writing. That won't stay automatically true — every time a new rule (or a new i18n key) is added to `en.js`, every other locale needs the same key added, or it silently falls back to English for that string (see the fallback behavior below). `tests/i18n/i18n-locale-completeness.test.js` catches this: it fails the build if a locale listed in `FULLY_TRANSLATED_LOCALES` (currently `fr`, `de`, `es`) is missing any key present in `en.js`, and fails for *any* locale that has an orphaned key not in `en.js` (a sign of a typo or a stale key left behind after a rule was removed). Run `npm run i18n:report` any time to see per-locale coverage.
+Locale files are plain JSON: a flat map of key to translated string, in the same key order as `en.json`. Nothing else lives in them, so contributing a language means editing text and never touching code.
+
+Every locale carries every key `en.json` has. Keeping it that way is the job of `npm run i18n:sync`: run it after any change to `en.json` and it rewrites every non-English locale file to match — adding keys that are new, dropping keys `en.json` no longer has, and leaving existing translations alone. A key it adds is seeded with the English text, which counts as untranslated until someone replaces it.
+
+Forget to run it and the build fails: `tests/i18n-sync.test.js` and `tests/i18n/i18n-locale-completeness.test.js` reject a missing key, an orphaned key, or any file that `i18n:sync` would rewrite. `npm run i18n:check` reports the same thing without touching the files, and `npm run i18n:report` prints per-locale coverage.
 
 ## Selecting a locale
 
@@ -19,17 +23,87 @@ All four locales are fully translated as of this writing. That won't stay automa
 runDomRulesInPage(url, null, { locale: 'fr' }, null);
 ```
 
-Default is `'en'` if omitted. Any string is accepted — an unrecognized locale (e.g. `'ja'`, not yet built) behaves exactly like a locale that's 0% translated: every string falls through to English (see below), not an error.
+Default is `'en'` if omitted. Any string is accepted; an unrecognized locale is never an error.
+
+## How a locale is chosen
+
+Two things happen, in this order. Getting them mixed up is the usual source of confusion, so they are described separately.
+
+### Step 1 — pick a dictionary (once per scan)
+
+1. Use the dictionary matching your code. `de` finds `de.json`. Case doesn't matter — `pt-br`, `pt-BR` and `PT-BR` all find `pt-BR.json`.
+2. Otherwise, drop everything after the first `-` and try that. `de-DE` finds `de.json`; so does `de-AT`.
+3. Otherwise, use English.
+
+So you only need a `de-DE.json` if German in Austria and Germany should actually read differently. Ship `de.json` and every German variant is covered.
+
+### Step 2 — resolve each string (per string)
+
+Within the chosen dictionary, every string is looked up on its own:
+
+1. Take the key's value from the chosen dictionary.
+2. If that key is missing, take the English one.
+3. If English is missing it too — which shouldn't happen for a built-in key, but can for a hand-rolled one — use the literal text the rule itself carries.
+
+The result is never a blank, an `undefined`, or a thrown error. A half-finished translation renders in your language where it exists and in English everywhere else. See `t()` in `scripts/build-core.js` for the exact implementation.
+
+## Knowing which locale you actually got
+
+Graceful fallback has one drawback: ask for a language the build doesn't carry and you get fluent English back, with nothing in the strings to say so. Every result therefore reports the resolution once, at the top:
+
+```json
+"engine": {
+  "tag": "a11ycore",
+  "schemaVersion": "1.0.0",
+  "locale": { "requested": "ja", "resolved": "en", "reason": "unknown-locale" }
+}
+```
+
+`requested` is what you asked for (after trimming; `en` if you passed nothing or a non-string), `resolved` is the dictionary that was used, and `reason` is one of:
+
+| `reason` | Meaning |
+|---|---|
+| `ok` | You got exactly what you asked for, and that dictionary carries every key. |
+| `primary-subtag` | Your code carried a subtag with no dictionary of its own, so its base language was used — you asked for `de-DE` and got `de`. Normal and expected; nothing to fix. A difference in case alone is not this: `DE` reports `ok`. |
+| `dictionary-not-loaded` | The project ships that language, but this copy of the engine doesn't carry it and none was supplied. In practice: the standalone browser bundle without its locale side file. |
+| `unknown-locale` | The project has no such translation at all, so English was used. `ja` and `pt-BR` both land here today. |
+| `partial-dictionary` | The dictionary was used but is missing some keys, so those individual strings fell back to English. |
 
-## Fallback behavior (per-string, not per-locale)
+Treat the list as open — a later release can add a value, so match on the ones you care about and let the rest fall through a default.
 
-Resolution happens independently for *every individual string*, not once for the whole scan:
+If you need a particular language, `requested !== resolved` is the condition to check in CI. Note it is also true for the harmless `primary-subtag` case, so gate on `reason === 'unknown-locale' || reason === 'dictionary-not-loaded'` if a base-language match is good enough for you. See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md#top-level-result) for the field's place in the result and [`API_STABILITY.md`](./API_STABILITY.md) for what is guaranteed about it.
 
-1. Look up the key in the requested locale's dictionary.
-2. If missing, fall back to the English (`en`) dictionary.
-3. If still missing (shouldn't happen for a built-in key, but true for anything hand-rolled), fall back to the literal string the rule itself provided as a default.
+## Where the dictionaries live
 
-This means requesting `locale: 'fr'` today gives you a real mix — translated strings where `fr.js` has the key, English strings where it doesn't — never a blank, `undefined`, or thrown error. See `t()` in `scripts/build-core.js` if you need the exact implementation.
+Which languages are available depends on how you load the engine.
+
+| How you load it | What you get |
+|---|---|
+| `require('@surea11y/core')` | Every locale, built in. Nothing to configure. |
+| A binding (Playwright, Cypress, …) | Every locale, built in. Nothing to configure. |
+| `surea11y.browser.js` in a `<script>` tag | English. Load `surea11y.i18n.<locale>.js` after it for anything else. |
+
+The bundle is split because it travels over the network to every page that uses it, and no page needs all four languages. Keeping English inline and the rest optional took about 280 KB off the download and stops it growing as languages are added. Nothing else changes: the Node package and the bindings are unaffected.
+
+```html
+<script src="surea11y.browser.js"></script>
+<script src="surea11y.i18n.de.js"></script>
+```
+
+Ask for a language whose file you didn't load and you get English, with `engine.locale.reason` set to `dictionary-not-loaded` — different from `unknown-locale`, which means the project has no such translation at all.
+
+### Supplying a dictionary yourself
+
+`engineOptions.messages` accepts `{ [locale]: { key: value } }` and takes precedence over anything built in or loaded from a side file. Useful for overriding a handful of strings, or for a language you maintain privately:
+
+```js
+runDomRulesInPage(url, null, {
+  locale: 'de',
+  messages: { de: { img_altPresent_title: 'Eigener Text' } }
+}, null);
+```
+
+Keys you don't supply fall back normally, so a partial override is fine.
 
 ## Where keys are used
 
@@ -40,11 +114,93 @@ Two independent key namespaces, both resolved the same way:
 
 Both are included in the result alongside the already-resolved text, so you can re-render in a different locale from a saved result without re-scanning — see the `i18n` field's presence in `OUTPUT_SCHEMA.md`.
 
-## Contributing a translation
+## Adding your language
+
+You do not need to know how the engine works, and you will not write any JavaScript beyond editing quoted strings. A translation is one data file.
+
+### 1. Get the repository running
+
+```sh
+git clone https://github.com/SureA11y/core.git
+cd core
+npm install
+```
+
+### 2. Create the file
+
+```sh
+npm run i18n:new pt-BR
+```
+
+That writes `src/i18n/pt-BR.json` containing every key `en.json` has, in the same order, each seeded with the English text as a placeholder. **Use the shortest code that identifies the language** — `pt`, `nl`, `pl`. A file named `pt.json` serves everyone who asks for `pt`, `pt-BR` or `pt-PT`, because a code with a subtag falls back to its base language. Name it `pt-BR.json` and only people who ask for exactly that get it; `pt` speakers elsewhere fall through to English.
+
+Add a regional file only when the wording genuinely has to differ, and add it alongside the base language rather than instead of it.
+
+The command refuses to overwrite a file that already exists. To pick up work on an existing locale, edit it directly.
+
+### 3. Translate the values
+
+Each entry is `"key": "text"`. Change only the text on the right:
+
+```json
+  "img_altPresent_title": "<img> must have an alt attribute",
+```
+
+becomes
+
+```json
+  "img_altPresent_title": "<img> precisa ter um atributo alt",
+```
+
+Four things to leave alone:
+
+- **The keys.** `img_altPresent_title` is an identifier the engine looks up. Renaming one breaks the lookup.
+- **`{{placeholder}}` tokens** — `{{ratio}}`, `{{element}}`, `{{role}}` and friends are substituted with real values at scan time. Keep them spelled exactly as in English. You may move them within the sentence if your grammar needs it.
+- **`{{#name}}…{{/name}}` and `{{^name}}…{{/name}}` blocks** — conditional sections, shown or hidden depending on the finding. Translate the text inside them; keep the markers.
+- **Code identifiers** — `<img>`, `aria-label`, `role="dialog"`, `alt=""`, CSS property names. These are things the reader will look for in their own source, so they stay in the original. A double quote inside a value has to stay escaped as `\"`, which is the one piece of JSON syntax you need.
+
+Write for someone fixing the page, not for a specialist: say what is wrong and what to do about it. Where your language has established accessibility vocabulary (a national WCAG translation, a government standard), follow it rather than inventing terms.
+
+If a string is genuinely identical in your language, leave it. It is counted as untranslated but behaves correctly.
+
+### 4. Check your progress
+
+```sh
+npm run i18n:report
+```
+
+Prints, per locale, how many values differ from English, plus any missing or orphaned keys. Anything still matching the English text is reported as untranslated — that is a progress signal, not an error.
+
+You do not need every string on day one. Per-string fallback means an unfinished locale renders in your language where you have translated it and in English everywhere else, which is exactly how `fr`, `de` and `es` started. Ship what you have.
+
+### 5. Before opening the pull request
+
+```sh
+npm run i18n:sync    # confirms your file matches en.json key-for-key
+npm test
+```
+
+`npm run build` also emits `surea11y.i18n.<locale>.js` for the standalone browser bundle — generated, so there is nothing for you to write.
+
+Then open a pull request touching `src/i18n/<locale>.json`, plus one row in the coverage table at the top of this file. Tell us which language and, if you use one, which national terminology standard you followed — that helps whoever reviews it later.
+
+Once a locale is in the repository it is maintained with the rest of the engine: when a new rule adds strings, `npm run i18n:sync` seeds them in your file in English and `npm run i18n:report` shows them as outstanding.
+
+## Maintaining the locales
+
+When you add, rename or remove a key in `src/i18n/en.json`:
+
+```sh
+npm run i18n:sync
+```
+
+Every other locale is rewritten to match — new keys seeded in English, removed keys dropped, existing translations untouched. The command is idempotent and prints what it changed per locale.
+
+| Command | Does |
+|---|---|
+| `npm run i18n:new <locale>` | Create a new locale file from `en.json`. Refuses to overwrite. |
+| `npm run i18n:sync` | Bring every locale file back in line with `en.json`. Add `-- <locale>` to restrict it to one. |
+| `npm run i18n:check` | Same comparison, writes nothing, exits non-zero on drift. |
+| `npm run i18n:report` | Per-locale translation coverage. |
 
-1. Scaffold the file: `npm run i18n:new <locale>` (e.g. `npm run i18n:new de`) creates `src/i18n/<locale>.js` with all of `en.js`'s keys already present, each seeded with the English text as a placeholder. It refuses to overwrite an existing locale file unless you pass `--force`.
-2. Replace the placeholder values with real translations, key by key. Leave any you're unsure about as-is for now — a value identical to English is treated as untranslated, not broken (see the fallback behavior above).
-3. Check progress any time with `npm run i18n:report` — it prints, per locale, how many keys have been translated vs. still match the English placeholder, plus any missing or orphaned keys.
-4. You don't need every key on day one — the fallback behavior above means a partial translation degrades gracefully to English per-string, exactly like `fr`/`de`/`es` did during their own early stages. Ship what you have. A partial locale is valid and won't fail `i18n-locale-completeness.test.js` unless you also add it to `FULLY_TRANSLATED_LOCALES` in that file — only do that once `npm run i18n:report` shows 100% coverage.
-5. Keep `{{placeholder}}` tokens (and `{{#foo}}...{{/foo}}` conditional blocks) in translated strings exactly as they appear in the English source — they're substituted/evaluated verbatim regardless of locale (e.g. `{{element}}`, `{{role}}`). Never translate HTML tag/attribute names (`<img>`, `aria-label`, `role="dialog"`, etc.) — they're code identifiers, not prose.
-6. Run `npm run build && npm test` to confirm nothing broke, including locale-completeness.
+`npm test` fails if a locale file has drifted, so an added key cannot reach `main` without every locale carrying it.

package/docs/INTEGRATION.md

@@ -107,7 +107,29 @@ Good for: a manual check against a page open in a real browser, a bookmarklet, o
 
 `a11ycore.runa11yCoreInPage` is the exact same function described in Pattern 2 above — the bundle exists only to solve *loading* it without `require`/a module system, not to add a separate API surface. It carries the same self-containment property (own inlined rule catalog, no free variables), which is what makes a plain `<script>` tag sufficient.
 
-Deliberately excluded from this bundle: `runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder`. Cross-frame scanning needs the embedded frame to load the engine and opt in too (see "Cross-frame scanning" below) — not a fit for a single dropped-in script tag. Use the npm package directly if you need it.
+### Scanning in a language other than English
+
+The bundle carries English only. Every other locale ships beside it as its own file — load one after the bundle and that language becomes available:
+
+```html
+<script src="node_modules/@surea11y/core/surea11y.browser.js"></script>
+<script src="node_modules/@surea11y/core/surea11y.i18n.de.js"></script>
+<script>
+  const result = a11ycore.runa11yCoreInPage(location.href, null, { locale: 'de' }, null);
+</script>
+```
+
+Load as many as you need; each adds one language and they don't interfere. Order matters only in that the bundle has to come first — a side file loaded on its own throws with a message saying so.
+
+Ask for a locale whose file you haven't loaded and you get English, not an error, with `result.engine.locale.reason` set to `dictionary-not-loaded` so it's visible rather than silent. See [`I18N.md`](./I18N.md).
+
+Why the split: the bundle is fetched over the network, and every language would otherwise be paid for by every page whether used or not. Keeping English inline and the rest optional took roughly 280 KB off the download and stops it growing as languages are added. The Node package is unaffected — `require('@surea11y/core')` still has every locale built in.
+
+If you'd rather supply a dictionary yourself, `engineOptions.messages` takes `{ [locale]: { key: value } }` directly and wins over a loaded side file.
+
+### What the bundle leaves out
+
+Deliberately excluded: `runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder`. Cross-frame scanning needs the embedded frame to load the engine and opt in too (see "Cross-frame scanning" below) — not a fit for a single dropped-in script tag. Use the npm package directly if you need it.
 
 ## Scoping a scan to part of the page
 
@@ -139,11 +161,11 @@ Notes for CI specifically:
 
 ### Cross-frame scanning (including cross-origin)
 
-`runa11yCoreInPage` only ever scans the single document it runs in — it has no visibility into `<iframe>` content, same-origin or not. For most uses that's fine (rules apply to the current document; a consumer running once per frame, e.g. once per content-script injection into `all_frames: true`, already covers every frame independently). But sometimes you want ONE scan's result to include what's inside embedded frames too — payment widgets, cookie-consent dialogs, third-party embeds — the same real scenario other engines' own cross-frame messaging protocols exist for.
+`runa11yCoreInPage` only ever scans the single document it runs in — it has no visibility into `<iframe>` content, same-origin or not. For most uses that's fine (rules apply to the current document; a consumer running once per frame, e.g. once per content-script injection into `all_frames: true`, already covers every frame independently). But sometimes you want ONE scan's result to include what's inside embedded frames too — payment widgets, cookie-consent dialogs, third-party embeds — which is what the cross-frame functions below are for.
 
-`runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder` are a separate, additive pair of functions for exactly this — not needed at all if you're driving the browser with Puppeteer/Playwright (see "Pattern 2" above): an automation driver already reaches every frame unconditionally via CDP, which is strictly *better* than what's described here. This exists specifically for when there's **no automation driver** — a plain script/bundled widget/browser extension running inside the page itself, fully subject to the same-origin policy, exactly like other engines' equivalent mechanisms are.
+`runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder` are a separate, additive pair of functions for exactly this — not needed at all if you're driving the browser with Puppeteer/Playwright (see "Pattern 2" above): an automation driver already reaches every frame unconditionally via CDP, which is strictly *better* than what's described here. This exists specifically for when there's **no automation driver** — a plain script/bundled widget/browser extension running inside the page itself, fully subject to the same-origin policy.
 
-**How it works**: a parent frame's `runa11yCoreAcrossFrames()` call pings each direct child `<iframe>`/`<frame>` via `postMessage`; if — and only if — that child has *also* called `a11yCoreEnableFrameResponder()` (its own opt-in to being scannable from above), it runs its own scan and replies with the result, which the parent includes. **A non-cooperating frame (the common case for most third-party embeds you don't control) is simply unreachable** — this mirrors the same real limitation other engines have for non-cooperating frames; it is not a gap `surea11y` closes that they don't have either.
+**How it works**: a parent frame's `runa11yCoreAcrossFrames()` call pings each direct child `<iframe>`/`<frame>` via `postMessage`; if — and only if — that child has *also* called `a11yCoreEnableFrameResponder()` (its own opt-in to being scannable from above), it runs its own scan and replies with the result, which the parent includes. **A non-cooperating frame (the common case for most third-party embeds you don't control) is simply unreachable** — the same-origin policy allows no way around it from inside the page.
 
 ```js
 // Inside the embedded/child page (e.g. a widget's own bundle), once, at load:
@@ -167,8 +189,8 @@ for (const frame of result.frames) {
 
 A few things worth knowing:
 - **Async, unlike the other two runners** — `postMessage` round-trips can't be synchronous, so this is a separate, Promise-returning pair rather than an `engineOptions` flag on `runa11yCoreInPage` (which stays synchronous, unchanged, for every existing caller).
-- **`engineOptions.pingWaitTime`** (default `500`ms) and **`engineOptions.frameWaitTime`** (default `60000`ms) control how long a child frame gets to answer a ping and a full run request respectively, matching the defaults other engines use for the equivalent options.
+- **`engineOptions.pingWaitTime`** (default `500`ms) and **`engineOptions.frameWaitTime`** (default `60000`ms) control how long a child frame gets to answer a ping and a full run request respectively.
 - **No jsdom/Node equivalent** — this is browser-only. jsdom's window/frame model doesn't meaningfully represent independent-realm cross-origin `postMessage`, and the feature has no purpose in Node anyway.
 - **Bundler-free, like `runa11yCoreInPage`** — both functions are fully self-contained (their own private copy of the rule catalog and every helper they need), so raw-source injection (a bookmarklet, a content script with no build step) works with zero bundler needed, exactly like `runa11yCoreInPage` already does. If you *do* use a normal bundler/`require`/`import`, that works too, unchanged.
 - **Cost of that self-containment**: `src/core.js` grew from ~1.86MB to ~3.1MB, since these two functions each needed their own complete private copy of the rule catalog and shared helpers rather than sharing the outer `RULE_IMPLS`. If this file's size ever becomes a real problem, the fix would be to drop the bundler-free requirement for just these two functions (accepting that cross-frame scanning in "plain script injection" mode needs a real bundler, unlike `runa11yCoreInPage` alone) rather than tripling the embedded catalog again for some future feature.
-- **No origin/identity check on the sender** beyond the message's own namespaced envelope — matching the same permissiveness other engines take here. Running a read-only scan and replying with DOM-derived results isn't a privileged operation; the content involved is no more sensitive than what's already rendered on the page.
+- **No origin/identity check on the sender** beyond the message's own namespaced envelope. Running a read-only scan and replying with DOM-derived results isn't a privileged operation; the content involved is no more sensitive than what's already rendered on the page.

package/docs/LIMITATIONS.md

@@ -14,7 +14,7 @@ surea11y is a **static DOM scan**: it reads the DOM tree and computed styles at
 
 - **jsdom (Node, no real browser) has no CSS layout engine.** Rules needing real geometry — most notably `target-size-minimum` (WCAG 2.5.8, needs real `getBoundingClientRect()`) — report `notApplicable` under plain jsdom rather than guess. Run under a real browser (Puppeteer/Playwright — see [`INTEGRATION.md`](./INTEGRATION.md) Pattern 2) to get real findings from these rules.
 - **`<dialog>` and other elements hidden by the default UA stylesheet** (no `open` attribute, `display: none` by spec), along with any other subtree hidden via `display:none`, `visibility:hidden`, `[hidden]`, or closed `<details>`, are **excluded from rule evaluation by default** — matching the visibility-aware behavior of other established engines. This is a deliberate default (`engineOptions.includeHiddenElements: false`), not an oversight: hidden content isn't reachable by assistive technology or keyboard until it's shown, so flagging a markup defect inside it by default would often be noise. Set `engineOptions.includeHiddenElements: true` to evaluate hidden/collapsed subtrees anyway — e.g. to catch a markup defect (like a broken ARIA ID reference) before a dialog ever opens. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#engineoptions--the-rest) for the option and exactly which hiding mechanisms it covers.
-- **Static markup vs. live/post-hydration DOM state.** The rule logic itself is DOM-source-agnostic — it evaluates whatever DOM it's handed, whether that's jsdom-parsed static HTML (Pattern 1) or an already-loaded, already-hydrated real browser tab (Pattern 2, see [`INTEGRATION.md`](./INTEGRATION.md)). But the CLI (`npx @surea11y/cli scan <url>`) specifically fetches static HTML only, with no JS execution — see [the CLI docs](https://github.com/SureA11y/cli/blob/main/docs/CLI.md). For a JS-framework-hydrated widget whose server-rendered markup intentionally ships one state before client JS syncs it (e.g. `<input type="checkbox" aria-checked="true">` shipped before client JS sets the native `checked` property to match on hydration — an extremely common, entirely legitimate pattern), a CLI scan only sees the pre-hydration markup. Other engines running inside an actual loaded browser tab see the post-hydration state instead, so the two can disagree on exactly this class of element for reasons that have nothing to do with either engine's rule correctness. `aria-checked-state-mismatch` is deliberately `manual`/`cantTell`-capped for this exact reason rather than a hard `fail`. If you need live-DOM accuracy for hydration-sensitive checks, run the library directly against an already-loaded page via Pattern 2, not the static-fetch CLI.
+- **Static markup vs. live/post-hydration DOM state.** The rule logic itself is DOM-source-agnostic — it evaluates whatever DOM it's handed, whether that's jsdom-parsed static HTML (Pattern 1) or an already-loaded, already-hydrated real browser tab (Pattern 2, see [`INTEGRATION.md`](./INTEGRATION.md)). But the CLI (`npx @surea11y/cli scan <url>`) specifically fetches static HTML only, with no JS execution — see [the CLI docs](https://github.com/SureA11y/cli/blob/main/docs/CLI.md). For a JS-framework-hydrated widget whose server-rendered markup intentionally ships one state before client JS syncs it (e.g. `<input type="checkbox" aria-checked="true">` shipped before client JS sets the native `checked` property to match on hydration — an extremely common, entirely legitimate pattern), a CLI scan only sees the pre-hydration markup. A scan running inside an actual loaded browser tab sees the post-hydration state instead, so the two can disagree on exactly this class of element for reasons that have nothing to do with rule correctness. `aria-checked-state-mismatch` is deliberately `manual`/`cantTell`-capped for this exact reason rather than a hard `fail`. If you need live-DOM accuracy for hydration-sensitive checks, run the library directly against an already-loaded page via Pattern 2, not the static-fetch CLI.
 
 ## Deliberately not attempted — judgment calls, not automatable safely
 

package/docs/OUTPUT_SCHEMA.md

@@ -15,7 +15,11 @@ This is the exact shape of the object returned by `runDomRulesInPage(...)` / `ru
 
 ```ts
 {
-  engine: { tag: string, schemaVersion: string },
+  engine: {
+    tag: string,
+    schemaVersion: string,
+    locale: { requested: string, resolved: string, reason: string }
+  },
   url: string | null,
   title: string | null,
   timestamp: string | null,
@@ -31,6 +35,8 @@ This is the exact shape of the object returned by `runDomRulesInPage(...)` / `ru
 |---|---|
 | `engine.tag` | The engine's own identity tag, currently `"a11ycore"`. Every rule (built-in or custom) carries it in `meta.tags` — rule `ruleId`s themselves are bare (no prefix). |
 | `engine.schemaVersion` | The result-schema version (`"1.0.0"`). Bump-worthy if this document's shape ever changes incompatibly — pin to it if you're parsing output programmatically. See [`API_STABILITY.md`](./API_STABILITY.md) for the full stable/unstable field list and version-bump policy. |
+| `engine.locale` | Which dictionary the run actually used. `requested` is your `engineOptions.locale` after trimming (`"en"` if you passed nothing or a non-string); `resolved` is the locale whose dictionary was used; `reason` explains the pairing. Because locale fallback is graceful and per-string, asking for a language the build does not carry produces English text rather than an error — this field is how you find that out without reading the strings. Reported once per result: a run uses one dictionary throughout. |
+| `engine.locale.reason` | `"ok"` — you got the dictionary you asked for, and it carries every key. `"primary-subtag"` — your code had a subtag with no dictionary of its own, so its base language was used: `"de-DE"` resolves to `"de"`. `"dictionary-not-loaded"` — the project ships that language, but this build does not carry it and none was supplied (the standalone browser bundle, without its locale side file). `"unknown-locale"` — the project has no such translation at all. `"partial-dictionary"` — the dictionary was used but is missing keys English has, so those strings fell back to English. Treat the set as open; later releases can add to it. |
 | `url` | The `pageUrl` argument you passed in, or `document.location.href` if you passed `null`/omitted it, or `null` if neither is available. |
 | `title` | `document.title` at scan time, or `null`. |
 | `timestamp` | **Not auto-generated.** Only set if you pass `engineOptions.timestamp` as a non-empty string — the engine has no built-in clock (deterministic-by-design). If you want a scan timestamp in the result, supply it yourself. |
@@ -97,7 +103,7 @@ Notes:
 
 - **`outcome` vs `outcomeNormalized`**: identical except `notApplicable` becomes `"inapplicable"` in `outcomeNormalized`. Both are provided so you can match either your own vocabulary or the engine's internal one.
 - **`type: "manual"` rules can never report `outcome: "fail"`.** If a manual rule's own logic would have said `fail`, the engine coerces it to `cantTell` and appends an explanatory note to `error` — this is enforced centrally (`policy.coerceManualFailToCantTell`, on by default under the `a11y` policy contract; see [`POLICY.md`](./POLICY.md)), not something each rule has to remember. `fail` is reserved for deterministic, high-confidence, `type: "automatic"` findings only.
-- **`meta.normativeMappings`** is how a check result ties back to a WCAG Success Criterion — `[]` for rules with no formal WCAG mapping (other engines call these "Best Practices"; this engine calls them advisory `type: "manual"` rules). See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for how these roll up.
+- **`meta.normativeMappings`** is how a check result ties back to a WCAG Success Criterion — `[]` for rules with no formal WCAG mapping (this engine calls them advisory `type: "manual"` rules). See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for how these roll up.
 - **`error`**: only present if the rule implementation threw an uncaught exception, or if the manual-fail coercion above fired. A thrown rule always surfaces as `outcome: "cantTell"` with `occurrences: []` and `error` set to the exception message — the engine never lets one broken rule crash the whole scan.
 - **`engineOptions`** on each result is the *resolved* options object (after locale/contrast defaults were applied), not literally what you passed in — useful for confirming what a given rule actually saw, especially the resolved `locale` and `contrast.mode`/`contrast.rootCanvasFallback`.
 
@@ -185,7 +191,11 @@ const result = runDomRulesInPage(
 
 ```json
 {
-  "engine": { "tag": "a11ycore", "schemaVersion": "1.0.0" },
+  "engine": {
+    "tag": "a11ycore",
+    "schemaVersion": "1.0.0",
+    "locale": { "requested": "en", "resolved": "en", "reason": "ok" }
+  },
   "url": "https://example.test/",
   "title": "Example",
   "timestamp": null,

package/docs/REPORT.md

@@ -15,6 +15,8 @@ Open `report.html` directly from disk. Works alongside any other output mode —
 - **WCAG rollup**: grouped by conformance level (A / AA / AAA), sourced directly from the engine's own `rulesResults[]` composite rollups (`docs/WCAG_CONFORMANCE.md`) — one row per Success Criterion, its outcome, a pass/fail/needs-review/n/a breakdown, and which atomic rules contributed. This is real engine data, not an invented grouping — the same rollup you'd get from the raw JSON's `rulesResults`.
 - **Full technical data** (collapsed by default): a scorecard (tiles per outcome) and a searchable, filterable (by outcome), paginated table of every individual occurrence across the whole scan.
 
+The meta bar under the header carries the rule count, occurrence count, engine tag, schema version, and the locale the scan resolved to. Locale fallback is per-string and invisible in the text itself, so a report requested in a language the engine does not carry reads as an ordinary English one — the chip names the requested locale alongside the resolved one when the two differ. See [`I18N.md`](./I18N.md).
+
 ## Library usage
 
 ```js

package/docs/RULE_AUTHORING.md

@@ -132,6 +132,10 @@ The build/runtime resolves i18n by:
 2) falling back to `en` if missing,
 3) falling back to the literal `title`/`description` strings if still missing.
 
+Add the key and its English text to `src/i18n/en.json`, then run
+`npm run i18n:sync` so every other locale picks it up. `npm test` fails if you
+forget. See [`I18N.md`](./I18N.md).
+
 #### `meta.tags`
 Tags are used for grouping/filtering. Typical tag families in this ruleset include:
 - WCAG tagging: `wcag2a`, `wcag111`
@@ -163,6 +167,32 @@ const meta = {
 
 ---
 
+## 4.3 Reporting an occurrence
+
+Build occurrences with `helpers.reportOccurrence(element, { summary, hint, i18n, data })`
+rather than assembling the object by hand:
+
+```js
+occurrences.push(helpers.reportOccurrence(el, { summary: '…', hint: '…' }));
+```
+
+It attaches the element for the engine to finalize, which is how `selector`,
+`html` and `structuralPath` get filled in centrally instead of in each of the
+124 rules.
+
+**This is a performance contract, not just a convenience.** Every occurrence
+gets a `structuralPath`. Given the element, the engine computes it directly.
+Given only a hand-built occurrence, it re-finds the element with
+`document.querySelector(selector)` — one DOM query per occurrence. That is
+fine for a rule reporting a single document-level finding, and quadratic for
+one reporting many: `region` hand-built its occurrences and took four minutes
+on a thousand-element page, against under a second afterwards.
+
+`perfStats.counters['structuralPath.selectorFallback']` counts how often the
+engine had to re-find an element, so a slow rule can be spotted without
+guessing. `tests/structural-path-fallback.test.js` fails if that count starts
+growing with page size.
+
 ## 5) i18n in occurrences (repo reality)
 
 Occurrences also support i18n via keys + params.
@@ -189,6 +219,29 @@ At normalization time, the engine:
 Translation strings use `{{paramName}}` placeholders.
 `params` is shallow-copied and passed into interpolation.
 
+**A param carries a value, never prose.** Element names, roles, attribute names,
+selectors, ids, counts and ratios are values: they read the same in every
+language, because the author will search their own source for them. An English
+word or sentence is not, and passing one means it stays English in every locale
+— with nothing to reveal it, since the key is present everywhere and coverage
+reports look complete.
+
+When a message varies by case, give each case its own key rather than
+interpolating the differing text:
+
+```js
+// wrong: the sentence lives in the rule, so no locale can reach it
+i18n: { hintKey: 'myRule_hint_fail', params: { advice: 'Replace it with role="list".' } }
+
+// right: one key per case, each translatable on its own
+i18n: { hintKey: 'myRule_hint_fail_directory', params: { role } }
+```
+
+`tests/i18n/i18n-translatable-strings.test.js` fails any dictionary value with
+no translatable text of its own, which catches the `"{{advice}}"` shape above.
+It cannot catch a param carrying prose into an otherwise-normal sentence, so
+that one is on you.
+
 ---
 
 ## 6) Helpers contract used by rules (ctx.helpers)

package/docs/RULE_CATALOG.md

@@ -2,11 +2,11 @@
 
 Generated from the compiled engine's own catalog (`getChecksCatalog()`/`getRulesCatalog()`) — run `node scripts/generate-rule-catalog.js` after `npm run build` to regenerate this file whenever rules change. Do not hand-edit.
 
-**125 rules total: 77 automatic (WCAG-normative, can return `fail`), 48 manual (advisory/judgment-required, capped at `cantTell`). 101 carry at least one formal WCAG Success Criterion mapping.**
+**125 rules total: 76 automatic (WCAG-normative, can return `fail`), 49 manual (advisory/judgment-required, capped at `cantTell`). 101 carry at least one formal WCAG Success Criterion mapping.**
 
 See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`severity` mean on a scan result, and [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for how these roll up to an SC-level conformance claim. For WCAG-facet-level coverage-gap tracking (which parts of an SC are and aren't automatable yet), see `coverage/coverage-report.md` instead — that one is organized by facet, this one by rule.
 
-## Automatic rules (77) — can return `fail`
+## Automatic rules (76) — can return `fail`
 
 | Rule ID | Title | WCAG SC | Level | Confidence | Default severity |
 |---|---|---|---|---|---|
@@ -15,7 +15,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | `aria-allowed-role` | Explicit role must be permitted for its host element | 4.1.2 | A | high | moderate |
 | `aria-braille-equivalent` | aria-braillelabel/aria-brailleroledescription must have a non-braille equivalent | 4.1.2 | A | high | serious |
 | `aria-conditional-attr` | aria-errormessage requires aria-invalid to be set to a non-false value | 4.1.2 | A | high | serious |
-| `aria-deprecated-role` | role attribute must not use a deprecated or author-prohibited ARIA role | 4.1.2 | A | high | moderate |
+| `aria-deprecated-role` | role attribute should not use a deprecated or author-discouraged ARIA role | 4.1.2 | A | high | moderate |
 | `aria-hidden-body` | The document <body> must not be aria-hidden | 1.3.1, 4.1.2 | A | high | critical |
 | `aria-hidden-focus` | ARIA hidden elements must not be focusable | 2.4.7, 4.1.2 | AA | high | serious |
 | `aria-prohibited-attr` | ARIA naming attributes must not be used on roles that prohibit them | 4.1.2 | A | high | moderate |
@@ -28,10 +28,9 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | `aria-valid-attr` | aria-* attributes must be real, defined ARIA attributes | 4.1.2 | A | high | serious |
 | `aria-valid-attr-value` | aria-* attribute values must match their declared type | 4.1.2 | A | high | serious |
 | `autocomplete-valid` | autocomplete attribute must be a valid autofill value | 1.3.5 | AA | high | moderate |
-| `avoid-inline-spacing` | Inline style must not force text spacing with !important | 1.4.12 | AA | high | moderate |
+| `avoid-inline-spacing` | Inline style must not force text spacing below the WCAG metric | 1.4.12 | AA | high | moderate |
 | `binary-control-name-present` | Binary controls have an accessible name | 4.1.2 | A | high | serious |
 | `button-name-present` | Buttons have an accessible name | 4.1.2 | A | high | serious |
-| `bypass-blocks-present` | Page must provide a way to bypass repeated blocks | 2.4.1 | A | medium | serious |
 | `canvas-text-alternative-present` | <canvas> must provide a text alternative | 1.1.1 | A | high | serious |
 | `combobox-name-present` | Comboboxes have an accessible name | 4.1.2 | A | high | serious |
 | `contrast-computable` | Color contrast is computable for rendered text | 1.4.3, 1.4.6 | AAA | high | serious |
@@ -88,7 +87,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | `valid-lang` | Element lang attribute must be syntactically valid | 3.1.2 | AA | high | moderate |
 | `video-poster-text-alternative-present` | <video> poster must have a text alternative | 1.1.1 | A | medium | serious |
 
-## Manual rules (48) — advisory, capped at `cantTell`
+## Manual rules (49) — advisory, capped at `cantTell`
 
 | Rule ID | Title | WCAG SC | Level | Confidence | Default severity |
 |---|---|---|---|---|---|
@@ -97,6 +96,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | `area-alt-quality` | <area> alt text must be appropriate (manual review) | 1.1.1 | A | medium | minor |
 | `aria-checked-state-mismatch` | Native checkbox/radio aria-checked should match its actual state | 4.1.2 | A | medium | moderate |
 | `aria-text` | role="text" elements should have no focusable descendants | — | — | medium | minor |
+| `bypass-blocks-present` | Page must provide a way to bypass repeated blocks | 2.4.1 | A | medium | moderate |
 | `canvas-text-alternative-quality` | <canvas> text alternative must be appropriate (manual review) | 1.1.1 | A | medium | minor |
 | `css-hidden-focus` | Focusable elements must not be visually hidden | 2.4.7 | AA | low | serious |
 | `embed-text-alternative-quality` | <embed> text alternative must be appropriate (manual review) | 1.1.1 | A | medium | minor |

package/docs/TROUBLESHOOTING.md

@@ -2,7 +2,7 @@
 
 ## "I passed `runOnly: ['some-rule-id']` but every rule still ran"
 
-`runOnly` must be an object, not a bare array — `runOnly: ['img-alt-present']` is silently ignored (the engine falls through to "run everything"), because that shape has none of the fields the engine actually checks (`includeRuleIds`, `tags`, etc.). This is easy to get wrong if you're coming from another engine that does accept a bare array.
+`runOnly` must be an object, not a bare array — `runOnly: ['img-alt-present']` is silently ignored (the engine falls through to "run everything"), because that shape has none of the fields the engine actually checks (`includeRuleIds`, `tags`, etc.). A bare array is easy to reach for, so this is worth checking first.
 
 Fix:
 
@@ -41,7 +41,7 @@ Treat it as "needs a human to look" — it's neither pass nor fail by design. Mo
 
 ## "What happens if a locale is only partially translated?"
 
-Missing keys fall back to English per-string (never a blank or broken result), so a partial locale degrades gracefully rather than failing outright — see [`I18N.md`](./I18N.md) for the mechanism and current coverage. Both shipped locales (`en`, `fr`) are at full parity as of this writing, but that's not guaranteed to stay true automatically: adding a new rule adds a new key to `en.js`, and unless the same key is added to `fr.js` (or any other locale file you maintain), that string falls back to English until it is.
+Missing keys fall back to English per-string (never a blank or broken result), so a partial locale degrades gracefully rather than failing outright — see [`I18N.md`](./I18N.md) for the mechanism and current coverage. Key parity is enforced rather than hoped for: `npm run i18n:sync` carries any new or renamed `en.json` key into every other locale file, and the build fails if one is out of step. A key it adds holds the English text until someone translates it, so a locale can be behind on wording without ever being behind on keys.
 
 ## "`runDomRulesInPage` vs `runa11yCoreInPage` — which one do I want?"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/core",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Deterministic WCAG 2.2 accessibility engine that tells you what it can't tell you. Zero dependencies.",
   "keywords": [
     "accessibility",
@@ -61,6 +61,7 @@
     "src/checks/**/*.js",
     "bin/surea11y-core.js",
     "surea11y.browser.js",
+    "surea11y.i18n.*.js",
     "docs/**/*.md",
     "README.md",
     "LICENSE",
@@ -87,19 +88,25 @@
     "test:typography-helpers": "node tests/contrast-typography.test.js",
     "coverage": "node scripts/generate-wcag-coverage.js --rulesDir src/checks",
     "coverage:strict": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --strictFacets",
+    "coverage:check": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --check",
     "fixtures:index": "node scripts/generate-fixture-index.js",
     "docs:rule-catalog": "npm run build && node scripts/generate-rule-catalog.js",
     "validate:automatic-rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic",
     "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual",
+    "validate:rules": "npm run validate:automatic-rules && npm run validate:manual-rules",
     "i18n:new": "node scripts/i18n-scaffold.js",
+    "i18n:sync": "node scripts/i18n-sync.js",
+    "i18n:check": "node scripts/i18n-sync.js --check",
     "i18n:report": "node scripts/i18n-report.js"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "aria-query": "^5.3.2",
     "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.8.0",
     "jsdom": "^29.1.1",
+    "language-subtag-registry": "^0.4.2",
     "playwright": "^1.62.1",
     "prettier": "^3.9.6"
   }