docs(i18n): document the extract --check freshness gate

The docs and the i18n skill both presented `os i18n check` as *the* CI gate.
It is the coverage gate — it answers 'are the strings translated?'. For anyone
committing generated bundles that leaves the other half unguarded: renaming a
label, adding an object, or removing a spec key keeps coverage at 100% while
the bundles quietly go stale.

Documents the two as a pair, in both surfaces, since the skill is what ships to
third parties via `npx skills add`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UYLC8TfjzHGwatNxZKdX7H

Author: claude

content/docs/ui/translations.mdx

@@ -141,13 +141,29 @@ npx os i18n extract --locales zh-CN --fill todo --out src/translations
 
 # Report coverage; fail the build when it slips
 npx os i18n check --strict --threshold 95
+
+# Fail if the committed bundles have fallen behind the schema
+npx os i18n extract --locales zh-CN --fill todo --out src/translations --check
 ```
 
 `os i18n check` exits non-zero on violations, so it works as a CI gate.
 A missing string in the **default** locale is an error; missing strings in
 other locales are warnings until you set `--strict` / `--threshold`. The Todo
 example ships a completeness test alongside its bundles — worth copying.
 
+The two gates answer different questions, and you want both. `os i18n check`
+asks *are the strings translated?* — a coverage number about human work.
+`os i18n extract --check` asks *are the generated bundles still what the schema
+produces?* — a freshness check about machine output. Renaming a field's label,
+adding an object, or removing a spec key leaves coverage at 100% while the
+bundles quietly go stale, which is exactly how this repo's own bundles ended up
+carrying translations for keys the schema had deleted (#3670).
+
+`--check` writes nothing: it re-renders and diffs against `--out`, naming each
+stale file and printing the regenerate command. It runs in the same **merge
+mode** as a normal extract, so it never asks anyone to re-translate — an
+up-to-date bundle re-extracts byte-identically.
+
 ## Current boundaries
 
 Honest limits worth knowing before you plan around them:

skills/objectstack-i18n/SKILL.md

@@ -398,6 +398,32 @@ locale are errors; `--strict` promotes non-default gaps to errors and
 `--show-keys` lists every missing key. `os lint --i18n-strict` folds the same
 gate into linting.
 
+### `os i18n extract --check` — freshness, not coverage
+
+If you commit **generated** bundles (`*.generated.ts` produced by
+`os i18n extract`), coverage is only half the gate:
+
+```bash
+os i18n extract <config> --locales=zh-CN,ja-JP --fill=default \
+  --out=src/translations --check
+```
+
+`--check` writes nothing. It re-renders what a real extract would produce and
+fails if that differs from what is committed in `--out`, naming each stale or
+missing file and printing the regenerate command.
+
+**Use both gates — they answer different questions.** `os i18n check` asks *are
+the strings translated?* (coverage: human work). `extract --check` asks *are the
+generated bundles still what the schema produces?* (freshness: machine output).
+Renaming a label, adding an object, or removing a spec key leaves coverage at
+100% while the bundles quietly go stale — which is exactly how the platform's
+own bundles ended up carrying translations for keys the schema had already
+deleted, plus fields with no entry in any locale.
+
+It runs in the same **merge mode** as a normal extract, so it never asks for
+re-translation: an up-to-date bundle re-extracts byte-identically. Requires
+`--out` — there is nothing to compare against without it.
+
 ### Diff & Coverage Schemas
 
 The spec models coverage results for tooling: `TranslationCoverageResult`