@daanvandenbergh/i18nkit 1.0.0

package/package.json

@@ -0,0 +1,77 @@
+{
+    "name": "@daanvandenbergh/i18nkit",
+    "version": "1.0.0",
+    "description": "Type-safe i18n for TypeScript - miss a translation and it's a compile error. Framework-agnostic core, optional React layer, and a Claude Code skill that sweeps for untranslated strings.",
+    "type": "module",
+    "author": "Daan van den Bergh",
+    "keywords": [
+        "i18n",
+        "internationalization",
+        "localization",
+        "typescript",
+        "type-safe",
+        "react",
+        "translations"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/daanvandenbergh/i18nkit.git"
+    },
+    "homepage": "https://github.com/daanvandenbergh/i18nkit#readme",
+    "bugs": {
+        "url": "https://github.com/daanvandenbergh/i18nkit/issues"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "sideEffects": [
+        "**/*.css"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./react": {
+            "types": "./dist/react/index.d.ts",
+            "default": "./dist/react/index.js"
+        },
+        "./styles.css": "./dist/react/styles.css",
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "skills"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json && cp src/react/styles.css dist/react/styles.css",
+        "test": "vitest run --passWithNoTests",
+        "test:watch": "vitest",
+        "typecheck": "tsc --noEmit",
+        "prepublishOnly": "npm run build"
+    },
+    "peerDependencies": {
+        "react": ">=18",
+        "react-dom": ">=18"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        },
+        "react-dom": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@types/react": "^19",
+        "@types/react-dom": "^19",
+        "@vitest/coverage-v8": "^3.2.7",
+        "jsdom": "^25",
+        "react": "^19",
+        "react-dom": "^19",
+        "typescript": "^5.6.0",
+        "vitest": "^3.0.0"
+    }
+}

package/skills/i18nkit-add-locale/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: i18nkit-add-locale
+description: Add one new locale to a project already built on i18nkit and carry every translation through - the compiler-guided counterpart to i18nkit-sweep. Adding the code to `new I18n({ locales })` grows the locale union `L`, so `tsc` turns every `defineTextCatalog` / `defineText` / `LanguageText` entry still missing that locale into a compile error: an exhaustive, exact worklist of what to translate, handed to you by the compiler. This skill edits the I18n config, then translates every erroring entry - preserving interpolation params, `${...}` placeholders, split rich-text fragments, and leaving brand / `i18n.uniform` words untouched - fanning the work across parallel agents when there are many, and loops `tsc` to green. It also covers what the compiler cannot see: for `@daanvandenbergh/blogkit` it enumerates and creates the translated body beside the default in each post's per-slug folder (front-matter + body), extends the post's single `hero.js` i18n map with the new locale (its hero rendered via blogkit's hero skill), and it hunts hardcoded locale lists (static params, hreflang, sitemaps, middleware) that name codes literally. Use this whenever the user wants to add, support, or ship a new language or locale, translate the whole site / app into another language, internationalize into German / French / Spanish / Japanese / etc., launch in a new country or market, or asks "how do we add <language>?" - even if they never name i18nkit. It EXTENDS an already-wrapped codebase to a new locale; if bare untranslated strings might still exist, run i18nkit-sweep FIRST so the compiler can see them, then this. Takes the new locale code and an optional endonym label.
+user-invokable: true
+argument-hint: "<locale> [endonym]   e.g. de  |  fr \"Français\"  |  pt-BR \"Português (Brasil)\""
+---
+
+# i18nkit-add-locale
+
+Extend a project already built on i18nkit to **one new locale**, end to end: add the locale to the
+config, translate every catalog entry the compiler now flags, and close the two gaps the compiler
+cannot see (blogkit posts, hardcoded locale lists). This is the **inverse of i18nkit-sweep**. The sweep
+has no compiler signal - it hunts the *absence* of a translator and needs a team reading every file.
+Adding a locale is the opposite: the moment the new code enters `new I18n({ locales })`, the locale
+union `L` grows and `LanguageText<L>` is a mapped type over it, so `tsc` reports **every** un-covered
+entry as a compile error. The worklist is exact and free; the skill's job is to fill it with **real**
+translations and to not miss the handful of things that live outside the type system.
+
+The bar is **100% coverage with shippable quality**: `tsc` green proves nothing is structurally
+missing, and every translation both **carries the source's meaning and intent** (never a literal
+word-for-word swap - see the principle below) and is **grammatically flawless native copy**, or is
+explicitly flagged for a human - never a silent guess (a fabricated translation compiles green and
+ships wrong copy, the exact failure the types exist to prevent).
+
+**Translate for meaning, not word-for-word, in perfect grammar - this is non-negotiable and the
+easiest thing to get wrong.** A literal rendering drags the source language's grammar and idiom into
+the target and reads as broken to a native customer; the right translation is often *not* the direct
+one (an idiom becomes a different idiom, a slogan is transcreated to land in the target culture, a
+stiff construction is reshaped to how a native actually speaks). Read what surrounds each string - what
+it is, who reads it, what the product means to convey to the customer - and translate that *intent*,
+with 100% correct grammar (every agreement, gender, case, plural, accent). `reference/translation-rules.md`
+carries the full principle; it is the first thing every translation agent must internalise.
+
+## The authority
+
+`reference/translation-rules.md` (in this skill's own directory) is the adjudicator: the compiler-vs-
+uncatchable split, how to edit the config, exactly how to translate each entry shape (static,
+parameterized, split rich text) while preserving params / placeholders / structure, what to **never**
+translate (`uniform`, brand, endonyms, data), when to flag `needs-review` instead of guessing, and the
+blogkit + hardcoded-list rules. **Read it now.** Let `<skill-dir>` be this skill's own directory
+(the folder holding this SKILL.md); resolve it to an absolute path and pass
+`<skill-dir>/reference/translation-rules.md` to every translation agent - it is what keeps quality
+high. (The skill is a drop-in: it carries its own rules and script, nothing here hardcodes a path.)
+
+## Inputs
+
+Everything after `/i18nkit-add-locale` is one raw string. Parse in prose:
+1. The **first token is the new locale code** (`de`, `fr`, `pt-BR`, `ja`). Required. If it is missing,
+   ask which language to add rather than guessing.
+2. The **remainder, if any, is the endonym label** (`"Français"`, `"Português (Brasil)"`) - the
+   locale's own native name for the picker. If omitted, supply the correct native name yourself and
+   show it for confirmation in Phase 0 (get diacritics / script right).
+
+## Phase 0 - Locate the config and confirm the entry
+
+Find the consumer's `I18n` instance: `new I18n({ locales: {...}, default: "..." })` (conventionally
+`app/i18n.ts`, often `export const i18n` with `type Locale = keyof typeof i18n.locales`). Read it to
+learn the **existing locales** (the keys of `locales`) and the **default**. Then decide the new entry:
+- `label` - the endonym (from the argument, or the correct native name you supply).
+- `htmlLang` - the BCP-47 document subtag / URL prefix (primary subtag `de`; a regional form `pt-BR`
+  only when the site distinguishes regional URLs). Omit when it equals the map key.
+- `locale` - the full `Intl` locale for formatting (`de-DE`, `fr-FR`). Omit when `htmlLang` suffices.
+
+Confirm the code is not already configured (if it is, this is a re-run - jump to Phase 2 to fill any
+gaps). If the codebase may still contain **bare, unwrapped** strings, note that those are invisible to
+this compiler-driven flow and recommend running **/i18nkit-sweep** first so every string is in a
+catalog the new locale can force. State the resolved entry to the user before editing.
+
+## Phase 1 - Add the locale (turn on the compiler)
+
+Make the **single** edit to the config's `locales` map: add the new entry, placed where it should
+appear in the picker (insertion order is picker order). Do **not** change `default`. Do **not** edit
+anything else yet - every downstream method reads the instance, so this one edit is what makes the new
+locale exist and what makes `tsc` start reporting the worklist.
+
+## Phase 2 - Let the compiler enumerate the worklist
+
+Run the consumer's typecheck - `npm run typecheck`, fallback `npx tsc --noEmit`. Every catalog entry
+still missing the new locale now errors (typically `Property '<newcode>' is missing in type ...` at the
+`i18n.defineTextCatalog(...)` / `defineText(...)` call site). **This list is the exhaustive worklist** -
+group the errors **by file**. `i18n.uniform(...)` entries will **not** appear (they cover every locale
+by construction); leave them alone. If the count is zero, every entry is already covered - skip to
+Phase 4.
+
+## Phase 3 - Translate every entry (fan out when there are many)
+
+Filling each entry is independent per file, so **shard the erroring files and translate in parallel** -
+the meticulous, throw-compute-at-it half. For a handful of files, do it inline. For many, spawn one
+`general-purpose` agent per shard of ~8-12 files, **all in one message** so they run concurrently
+(keep to ~10-12 at once; run more in a second batch). Give each agent this task (fill in the shard and
+the resolved rules path):
+
+> You are translating this project's i18nkit catalogs into a new locale: **`<code>` (`<language
+> name>`)**. **First read `<skill-dir>/reference/translation-rules.md`** - it is the exact rule for how
+> to translate each entry shape and what to never touch. The existing locales are `<list them>`; read
+> their values in each file first to match tone, register (formal vs. informal address), and voice.
+>
+> **Translate for meaning and intent, never word-for-word, in flawless native grammar - this is the
+> whole point of the task.** A literal translation is the #1 way to ship wrong copy: it carries the
+> source grammar and idiom into the target and reads as broken to a native customer. For every string,
+> look at its context - what it is (button, heading, error, legal line, marketing promise), who reads
+> it, and what the product means to convey to the customer - and translate that intent; the natural
+> native phrasing often diverges from the direct one (idioms, slogans, register), and when it does,
+> choose the natural one. Grammar must be 100% correct: every agreement, gender, case, plural, accent,
+> diacritic. Hold each entry to a professional native writer's standard, not a dictionary's.
+>
+> Your files: `<list the shard's paths>`.
+>
+> For every `defineTextCatalog` / `defineText` / `LanguageText` / `LanguageTextFn` entry in these
+> files, **add the single new key `<code>`** with a real translation. Preserve everything structural:
+> for parameterized entries keep the exact parameter types and arity of the sibling locales and reuse
+> every `${...}` value (reorder words for the target grammar, never the params); for split rich-text
+> keep the fragment count; convert HTML entities to literal Unicode. **Never** touch `i18n.uniform(...)`
+> entries (already covered), brand / product names, endonyms, or data values. Where a translation is
+> genuinely uncertain (slogan, legal phrase, domain jargon, tight length constraint), still add your
+> best draft **and** report it as `needs-review` with a one-line reason - never leave a blank, never
+> confidently guess legal/brand copy. **Do not run the compiler, do not spawn sub-agents, do not edit
+> anything but the new key in each entry.** Return, per file: the entries you translated, and the
+> `needs-review` list with `file:line` + reason.
+
+Collect every agent's result. Then **loop `tsc` to green yourself**: re-run the typecheck, and for any
+remaining error fix that entry (a missed file, a parameterized signature that drifted, an entity that
+broke a template). Green `tsc` = every catalog entry provably covers the new locale.
+
+## Phase 4 - Close the compiler-invisible gaps
+
+Run the bundled scanner over the source root (it needs the new code, and the existing codes + blog
+`contentDir` / `defaultLocale` / `extension` from the config if the defaults differ):
+
+```bash
+EXISTING_CODES="en nl" CONTENT_DIR="./blog" DEFAULT_CODE="en" <skill-dir>/scripts/scan.sh <newcode> "<src or .>"
+```
+
+It prints two lead sections - confirm each by reading, none is a verdict:
+1. **BLOGKIT POST WORKLIST** - each post is a `<contentDir>/<slug>/` folder; for each, the
+   `<slug>/<newcode>` body that must exist beside the default (`<slug>/<defaultLocale>` or the neutral
+   `<slug>/post`), and whether the post has a `hero.js`. If blogkit is in use: add the new locale to the
+   `Blog` config's `locales[]`, then create each listed body - **same slug**, front-matter human fields
+   + body translated per translation-rules.md, and extend the post's single `hero.js` `text` map with
+   the new locale (reusing its shared gradient), its per-locale JPEG rendered via blogkit's
+   `hero_image.md`. Posts are independent, so fan them out one-agent-per-post exactly like Phase 3 when
+   there are several; for long articles, hand the precise worklist to the author and point at blogkit's
+   own writing / hero skills rather than machine-translating a long body. Report any **hero locale gap**
+   or **broken hero reference**. If blogkit is not detected, say so and skip.
+2. **HARDCODED LOCALE-LIST LEADS** - lines in app code that name existing locale codes as literals
+   (`generateStaticParams`, hreflang / sitemap builders, middleware matchers, locale `switch`es).
+   These do not follow `L`, so the new locale is missing until they are updated. Add the new code, and
+   note where deriving the list from `i18n.list` would prevent the next recurrence.
+
+Also note whether the new locale has a **built-in picker flag** (the React `localeFlag` helper): if not,
+the picker shows just the label - fine, but say so, and mention a custom `renderFlag` can supply one.
+
+## Phase 5 - Verify and report
+
+1. **Prove it compiles.** Final `npm run typecheck` (fallback `npx tsc --noEmit`) must be green - state
+   it. If the project has a build, run it too. Never leave the tree non-compiling.
+2. **Report**, in the conversation, per `reference/translation-rules.md`'s "What done looks like":
+   - the **config diff** (the exact `locales` entry added);
+   - **`tsc` green** stated as the coverage proof, with the **translated-entries count**;
+   - the **`needs-review` list** - every flagged entry by `file:line` + reason, so a human reviews only
+     those;
+   - the **blogkit result** (posts created / handed off, hero locale gaps, or "not detected");
+   - the **compile-invisible coverage line**: hardcoded-list leads fixed or left as advice, and the
+     picker-flag note.
+   Offer to save a long report to `claude/reports/i18nkit-add-locale-<code>.md`.
+
+## Notes
+
+- **Why compiler-driven, not a blind team:** unlike the sweep, the catalog worklist is exact and
+  provided by `tsc` - so the skill leans on the compiler for *what* to translate and spends its agents
+  on the part that is actually parallel and judgment-heavy (*translating* many entries / posts well).
+  Don't re-implement enumeration the compiler already does.
+- **The blogkit half is the real risk.** It is the one place a new locale is not compile-checked and
+  has no runtime fallback, so a missed post is a live broken page - never let the green `tsc` lull you
+  into skipping Phase 4.
+- **Portability:** the default fan-out uses the `Agent` tool; the same finder -> per-shard translate ->
+  verify shape maps onto a `Workflow` for a very large catalog, but Agent parallelism is enough for
+  most repos. The skill makes no repo-specific assumptions - it reads the locale set from the project's
+  own `I18n` config and its own bundled rules/script by relative path, and degrades from
+  Next/React-specific guidance (`generateStaticParams`, `app/i18n.ts`) to a generic `src/` project.
+- **Re-runnable:** run it again for the same code to fill any gap left by later-added copy, or run
+  /i18nkit-sweep first to guarantee every string is wrapped before you add the locale.

package/skills/i18nkit-add-locale/reference/translation-rules.md

@@ -0,0 +1,207 @@
+# i18nkit-add-locale rules - what a correct translation is, and what the compiler can't see
+
+This is the adjudicator for adding a locale. The job has two halves with very different guarantees,
+and getting the split right is the whole skill:
+
+1. **Catalog entries are compiler-enforced.** Every user-facing string already lives in a
+   `LanguageText<L>` / `LanguageTextFn<L, A>` - a mapped type over the locale union `L`. Adding the
+   new code to `new I18n({ locales })` grows `L`, so `tsc` reports every entry still missing the new
+   key as a compile error. That error list **is** the exhaustive worklist: when `tsc` is green, every
+   catalog entry provably covers the new locale. You do not hunt for these - the compiler hands them
+   to you, exactly.
+2. **A few things the compiler cannot see** and that therefore need a direct check: `@daanvandenbergh/blogkit`
+   post files (content, localized file-per-language in a per-slug folder - one body per language plus a
+   per-post `hero.js` - with **no** silent fallback, so a missing file is a broken page), hardcoded
+   locale-code lists in app code (static params, hreflang, sitemaps, middleware matchers) that enumerate
+   locales literally instead of from `i18n.list`, and whether the new locale has a built-in picker flag.
+   None of these move `L`, so none of them error.
+
+The bar is **a real, shippable, grammatically-flawless translation that carries the source's meaning
+and intent** for every entry, with anything genuinely uncertain flagged for a human - never a silent
+guess. A fabricated or sloppy translation is worse than a flagged gap: it compiles green and ships
+wrong copy to real users, which is exactly the failure the type system exists to prevent. Translate
+confidently where the language and the copy are unambiguous; flag where they are not.
+
+## Translate for meaning and intent - never word-for-word - in flawless native grammar
+
+**This is the heart of the job and the easiest thing to get wrong - read it before you translate a
+single string.** Do **not** translate literally. A word-for-word rendering of the source is the single
+most common way to ship copy that is technically "translated" and still wrong: it drags the source
+language's grammar, idiom, and word order into a language where they read as broken, foreign, or
+unintentionally comic - and a native customer notices *instantly*, the same way you would notice a
+clumsily-translated foreign product. Your task is not to swap words; it is to carry the **meaning and
+intent** across so the result reads as though it were originally written in the target language, not
+translated into it.
+
+- **Read the context first - always.** Look at what surrounds each entry: is this string a button, a
+  heading, a tooltip, a validation error, a legal line, a marketing promise? Who reads it, in what
+  moment, and what is the product trying to make that customer understand, feel, or do here? The same
+  English word is translated differently in a three-word CTA than in an error message. You are bringing
+  the author's intent to the customer - translate the *purpose* of the string, not just its characters.
+- **Prefer the phrasing a native speaker would actually use over the one closest to the source.** Very
+  often the right translation is **not** the direct one: an idiom becomes a different idiom (or plain
+  language), a slogan is rewritten to land in the target culture (this is transcreation, not
+  translation), a construction that is natural in the source reads stiff or wrong in the target and must
+  be reshaped. When the natural native phrasing diverges from the literal source, **choose the natural
+  one every time.** Faithful to meaning beats faithful to words.
+- **Grammar must be 100% correct - there is no "good enough".** Every ending, agreement, gender, case,
+  article, plural, contraction, accent, and diacritic must be right. A single grammatical error is the
+  tell that a page was machine-translated and it corrodes trust in the entire product the way a typo on
+  the homepage does. Hold every entry to the standard of a professional native writer, not a dictionary.
+  Where correct grammar depends on a runtime value - the grammatical gender of an interpolated noun,
+  plural agreement with a count, a case ending that changes with the inserted word - the string shape
+  may not be able to stay correct for all inputs: treat that as a real linguistic problem, flag it
+  `needs-review`, and describe it, rather than shipping a form that is only sometimes grammatical.
+- **When meaning can't be preserved faithfully without more context** - an ambiguous source string, a
+  term of art, a pun, a brand voice you cannot verify - translate to your best judgment and flag it
+  `needs-review` with the *specific* doubt. Meaning you are unsure of is exactly what a human confirms;
+  never paper over it with a confident literal guess.
+
+The two requirements hold **together**: the source's meaning and intent must survive, **and** the result
+must be grammatically flawless, natural native copy. A translation that satisfies only one of them is a
+defect, not a draft - a beautiful literal sentence with wrong intent fails, and a correct-meaning
+sentence with broken grammar fails.
+
+## Editing the I18n config (the switch that turns on the compiler)
+
+Add one entry to the instance's `locales` map (conventionally in `app/i18n.ts`):
+
+```ts
+locales: {
+    en: { label: "English" },
+    nl: { label: "Nederlands", htmlLang: "nl", locale: "nl-NL" },
+    de: { label: "Deutsch", htmlLang: "de", locale: "de-DE" },   // <- the new entry
+},
+```
+
+- **`label` is the endonym** - the locale's own native name, shown in the picker in every UI language
+  alike (`Deutsch`, `Français`, `Português (Brasil)`, `日本語`). It is **not** copy and is **not**
+  translated into the other UI languages. Get the native spelling right (correct diacritics, script).
+- **`htmlLang`** is the BCP-47 document subtag and the URL prefix (`/de/...`). Use the primary subtag
+  (`de`, `fr`), or a primary-region form (`pt-BR`) only when the site deliberately distinguishes
+  regional variants in its URLs. It defaults to the map key, so it can be omitted when the key is
+  already the subtag you want.
+- **`locale`** is the full BCP-47 `Intl` formatting locale (`de-DE`, `fr-FR`, `pt-BR`) used for
+  dates/numbers. Set it when the region matters for formatting; it defaults to `htmlLang`.
+- **Insertion order is the picker order** - place the new entry where it should appear in the list.
+- **Do not touch `default`.** Adding a locale never changes the fallback locale.
+
+Add the entry in one place only. Every downstream method (`translator`, `localizeHref`,
+`resolveLocale`, the picker, hreflang) reads the instance, so nothing else in well-built consumer code
+needs a second edit for the locale to *exist* - the remaining work is filling in its translations.
+
+## Translating a catalog entry - preserve every structural token, translate the copy for meaning
+
+This section is the mechanics; it sits **under** the meaning-and-grammar principle above, never against
+it. "Preserve structure" means keep the code intact (params, `${...}`, fragments, object shape) - it
+does **not** mean translate the words literally. Translate the copy for meaning and intent, in flawless
+grammar, *while* keeping every structural token below exactly as it is.
+
+You are adding **one new key** to an existing entry. Never remove or reword the other locales' values,
+never reformat the object, never add or delete entries.
+
+- **Static text** (`LanguageText`): add the new key with the translated string.
+  `{ en: "Save changes", nl: "Wijzigingen opslaan" }` -> add `de: "Änderungen speichern"`.
+- **Parameterized text** (`LanguageTextFn`): every locale shares **one** argument tuple `A`. Add a
+  builder with the **same parameter types and arity** as the sibling locales - you may rename the
+  parameters, but never add, drop, or retype one, or `A` changes and it will not compile. Translate
+  the template body and **reorder the words freely for the target grammar** - that is the entire
+  reason this is a function per locale (each language keeps its own word order). Use **every**
+  interpolated value the siblings use; dropping one silently loses that data.
+  `{ en: (name: string) => \`Welcome back, ${name}\` }` -> add
+  `de: (name: string) => \`Willkommen zurück, ${name}\``. Keep every `${...}` expression byte-identical
+  (they are code, not words).
+- **Split rich text** (a sentence deliberately broken into several `LanguageText` fragments composed
+  in JSX): translate **each fragment**, keeping the same number of fragments. The natural break point
+  may fall at a different word in the target language - that is fine; translate for meaning across the
+  fragments, do not force a word-for-word alignment that reads wrong.
+- **HTML entities -> the literal Unicode char** (`&middot;` -> `·`, `&rsquo;` -> `'`, `&nbsp;` -> a real
+  non-breaking space), matching how the other locales are authored.
+- **Match register and tone.** Read the existing locales first to gauge the voice (marketing vs.
+  formal, `du` vs. `Sie`, `tu` vs. `vous`) and keep the new locale consistent with it across the whole
+  catalog. Consistency of address form matters as much as literal accuracy.
+- **Numbers, dates, currency** are formatted at runtime via `i18n.intlLocaleFor(locale)` - never bake
+  a formatted number or a currency symbol into the translated string.
+
+## Never translate these (leave them exactly as they are)
+
+- **`i18n.uniform("...")` entries.** `uniform` generates the value for **every** locale code at
+  runtime, so the new locale is already covered - these never appear in the `tsc` error list. Do not
+  "add a key" to them; do not convert them.
+- **Brand and product names, proper nouns, the wordmark.** A product name is not translated (`"Acme
+  Pro"` stays `"Acme Pro"`). If a name is genuinely rendered differently in the target market, that is
+  a `needs-review` call for a human, not a guess.
+- **Machine/data values** that were never copy in the first place: enum keys, ids, URLs, CSS classes,
+  `<option value>` keys, currency/tax codes. These are not in the catalogs and do not concern you.
+- **Existing locales' values.** You are only ever adding the new key.
+
+## Flag - do not silently translate - when
+
+Add the new key with your best translation **and** list the entry as `needs-review` (with a one-line
+reason) whenever the copy is: a marketing slogan or tagline where literal translation reads wrong, a
+legally-loaded phrase (consent, liability, pricing terms), domain jargon or an industry term of art, a
+UI string whose length constraint could break layout in the target language, or anything where meaning
+is genuinely ambiguous without product context. Provide the draft so the human reviews rather than
+writes from scratch, but make the uncertainty explicit. Never leave an entry blank to "compile later" -
+a blank does not compile, and a fabricated confident translation of legal/brand copy is the one
+outcome worse than a flagged draft.
+
+## blogkit post translation - the compiler-invisible content half
+
+If the project uses `@daanvandenbergh/blogkit`, adding a locale to i18nkit does **not** create the
+blog's translations - blogkit localizes **file-per-language inside a per-slug folder**, and it has
+**no** silent fallback, so every post needs a body file for the new locale or that page is broken.
+
+Each post is a **folder**: `<contentDir>/<slug>/` holds one `<locale><ext>` body per language (the
+default is `<slug>/<defaultLocale><ext>`, e.g. `en.mdx`; a neutral `<slug>/post<ext>` is the fallback
+name), plus a single `<slug>/hero.js` that renders every language's hero. (Extension defaults to `.mdx`.)
+
+1. **Add the new locale to the `Blog` config** (`locales[]` with its `code`/`label`) so blogkit serves
+   it, and cross-check that its locale set now matches the `I18n` locales - a divergence between the two
+   is its own finding.
+2. **For every post folder**, create the translated body `<contentDir>/<slug>/<newcode><ext>` beside the
+   default - **same slug** (routing depends on the folder name), translated:
+   - **Front-matter**: translate the human fields (`title`, `excerpt`/`description`, and `tags` only if
+     the site shows localized tag labels - otherwise leave tags as shared keys). Keep every front-matter
+     **key** and every non-copy value (dates, slugs, ids) unchanged.
+   - **Body**: translate prose. Leave code blocks, inline code, identifiers, URLs, and MDX component
+     names/props untouched. Keep the heading structure and any anchors.
+   - **Hero** (`<slug>/hero.js`): the hero is **not** a carried-over image path - it is one i18n-style
+     data file per post, `export default (locale) => ({ gradient, ...text[locale] })`, whose `text` map
+     holds each language's `title`/`subtitle`. Add the new locale's entry to that `text` map, **reusing
+     the post's single shared `gradient`** (never re-pick it) so the language renders with matching art.
+     A per-locale JPEG is then rendered to `public/assets/blog/<slug>/hero.<newcode>.jpg` and the new
+     `<newcode><ext>`'s `image:` front-matter pointed at **its own** file - never at another locale's
+     JPEG (each hero bakes in that language's text). Rendering runs headless Chrome, so hand it to
+     blogkit's `hero_image.md`; if a post's `hero.js` is still the single-language plain-object form,
+     converting it to the `(locale) => params` map is likewise blogkit's job. Flag a `hero locale gap`
+     if a post's `hero.js` (or its rendered JPEG) is missing the new locale, and a `broken hero
+     reference` if a translation's `image:` has no file under `public/` or points at another locale's JPEG.
+3. Translating full article bodies is content authoring - for anything beyond short posts, hand the
+   precise per-post worklist to the author and point at blogkit's own `skills/blogkit` writing skill and
+   its `hero_image.md` skill rather than machine-translating a long article silently. (If the project
+   annotates `hero.js` with `@satisfies {Record<Locale, …>}` and runs `checkJs`, `tsc` may also surface
+   a missing locale there - a bonus, not the mechanism you rely on.)
+
+## Hardcoded locale lists - the other compiler-invisible gap
+
+Well-built consumer code enumerates locales from `i18n.list` / `i18n.locales`, so adding a locale flows
+through automatically. A **literal** list of codes does not - it is the anti-pattern that leaves the new
+locale half-wired. Look for and update: `generateStaticParams` returning a fixed `[{ locale: "en" }, ...]`,
+hreflang/sitemap builders iterating a bare `["en","nl"]`, a middleware matcher listing locale prefixes,
+or a `switch`/map keyed on locale codes. The bundled `scripts/scan.sh` surfaces these as leads; confirm
+each by reading the file - the fix is either to add the new code or (better, noted as advice) to derive
+the list from `i18n.list`.
+
+## What "done" looks like - the report
+
+- **The config diff**: the exact `locales` entry added (code, label, htmlLang, locale).
+- **`tsc` is green**: state it explicitly - that is the proof that every catalog entry now covers the
+  new locale. (Run the consumer's `npm run typecheck`, fallback `npx tsc --noEmit`.)
+- **A translated-entries count** and a **`needs-review` list**: every entry translated, with the flagged
+  ones called out by `file:line` and reason, so a human reviews exactly those and not the whole set.
+- **blogkit result**: posts created / handed off, plus any hero locale gap or broken hero reference; or
+  "blogkit not detected - skipped".
+- **Compile-invisible coverage**: the hardcoded-list leads that were fixed or left as advice, and a
+  one-line note if the new locale has **no built-in picker flag** (the picker falls back to its label;
+  a custom `renderFlag` can supply one) - not a bug, just so nothing is silently missing.

package/skills/i18nkit-add-locale/scripts/scan.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+#
+# scan.sh - the compile-invisible checks for i18nkit-add-locale.
+#
+# Adding a locale to `new I18n({ locales })` grows the union `L`, so `tsc` already hands you an
+# exhaustive worklist of every catalog entry to translate. This script covers only the two things
+# the compiler CANNOT see, because neither moves `L`:
+#   1. BLOGKIT POST WORKLIST - for each post folder <slug>/, the <slug>/<newcode> body the new locale
+#      needs beside the default (@daanvandenbergh/blogkit localizes file-per-language inside a per-slug
+#      folder with NO fallback, so a missing file is a broken page), plus whether the post has a
+#      hero.js whose per-locale text map + rendered JPEG must gain the new locale.
+#   2. HARDCODED LOCALE-LIST LEADS - app code that names locale codes as literals (generateStaticParams,
+#      hreflang/sitemap builders, middleware matchers, locale switches) instead of reading i18n.list,
+#      so the new locale is missing there until it is added by hand.
+#
+# Every line printed is a LEAD, not a verdict - confirm each by reading the file against
+# reference/translation-rules.md. It errs toward over-reporting; the agent's judgment decides.
+#
+# Usage:   scan.sh <new-locale-code> [source-root]        (source-root default: src)
+# Env:     EXISTING_CODES="en nl"   the currently-configured codes, for the hardcoded-list grep
+#          CONTENT_DIR="./blog"     blogkit content root (from the Blog config; default ./blog)
+#          DEFAULT_CODE="en"        blogkit default locale (names the base body <slug>/<default><ext>;
+#                                   from the Blog config; default en)
+#          EXT=".mdx"               blogkit post extension (from the Blog config; default .mdx)
+#          CONFIG_FILE="app/i18n.ts"  the I18n config file to exclude from leads (it is meant to
+#                                     name every code; excluding it drops the obvious false leads)
+
+set -euo pipefail
+
+NEWCODE="${1:-}"
+ROOT="${2:-src}"
+EXISTING_CODES="${EXISTING_CODES:-}"
+CONTENT_DIR="${CONTENT_DIR:-./blog}"
+DEFAULT_CODE="${DEFAULT_CODE:-en}"
+EXT="${EXT:-.mdx}"
+CONFIG_FILE="${CONFIG_FILE:-}"
+
+if [ -z "$NEWCODE" ]; then
+    echo "usage: scan.sh <new-locale-code> [source-root]   (EXISTING_CODES / CONTENT_DIR / DEFAULT_CODE / EXT / CONFIG_FILE via env)" >&2
+    exit 2
+fi
+
+echo "############################################################"
+echo "# i18nkit-add-locale compile-invisible scan"
+echo "#   new locale : $NEWCODE"
+echo "#   source root: $ROOT"
+echo "#   blog dir   : $CONTENT_DIR  (default $DEFAULT_CODE, extension $EXT)"
+echo "# These are LEADS ONLY - confirm each by reading the file."
+echo "############################################################"
+
+# ---------------------------------------------------------------------------
+echo
+echo "== SECTION 1: BLOGKIT POST WORKLIST (folder-per-slug, file-per-language, no fallback) =="
+echo "   Each post is a $CONTENT_DIR/<slug>/ folder with one <locale>$EXT body per language (the"
+echo "   default is <slug>/$DEFAULT_CODE$EXT, or the neutral <slug>/post$EXT). For each, the"
+echo "   <slug>/$NEWCODE$EXT that must exist. blogkit has no silent fallback, so a MISSING file"
+echo "   renders as a broken page."
+if [ -d "$CONTENT_DIR" ]; then
+    found_post=0
+    for dir in "$CONTENT_DIR"/*/; do
+        [ -d "$dir" ] || continue
+        slug="$(basename "$dir")"
+        # The default-locale body names the post: prefer <default>$EXT, fall back to the neutral post$EXT.
+        if [ -f "$dir$DEFAULT_CODE$EXT" ]; then
+            base="$dir$DEFAULT_CODE$EXT"
+        elif [ -f "${dir}post$EXT" ]; then
+            base="${dir}post$EXT"
+        else
+            base=""
+        fi
+        if [ -z "$base" ]; then
+            # No default-locale body: any <locale>$EXT here is an orphan translation (base renamed/
+            # deleted). A folder with no bodies at all is not a post - stay quiet.
+            for tr in "$dir"*"$EXT"; do
+                [ -e "$tr" ] || continue
+                echo "   ORPHAN  : $tr  (no $DEFAULT_CODE$EXT / post$EXT base body in $slug/ - stale)"
+            done
+            continue
+        fi
+        found_post=1
+        target="$dir$NEWCODE$EXT"
+        # The hero is one <slug>/hero.js exporting (locale)=>params with a per-locale `text` map; the new
+        # locale needs a `text` entry there AND a rendered public/.../hero.$NEWCODE.jpg (translation-rules.md).
+        if [ -f "${dir}hero.js" ]; then
+            hero="  [has hero.js - add \"$NEWCODE\" to its text map + render hero.$NEWCODE.jpg]"
+        else
+            hero=""
+        fi
+        if [ -f "$target" ]; then
+            echo "   ok      : $target$hero"
+        else
+            echo "   MISSING : $target$hero"
+        fi
+    done
+    if [ "$found_post" -eq 0 ]; then
+        echo "   (no <slug>/ post folders with a $DEFAULT_CODE$EXT / post$EXT body in $CONTENT_DIR - nothing to translate here)"
+    fi
+else
+    echo "   (no $CONTENT_DIR directory - blogkit not detected; skip this section unless the blog"
+    echo "    content root lives elsewhere, then re-run with CONTENT_DIR set)"
+fi
+
+# ---------------------------------------------------------------------------
+echo
+echo "== SECTION 2: HARDCODED LOCALE-LIST LEADS =="
+echo "   Lines naming existing codes as string literals - these do NOT follow the locale union L,"
+echo "   so $NEWCODE is missing there until added (prefer deriving the list from i18n.list)."
+
+if [ -z "$EXISTING_CODES" ]; then
+    echo "   (set EXISTING_CODES=\"en nl ...\" to scan for hardcoded lists - skipped)"
+else
+    # Build an alternation of the existing codes as QUOTED string literals ("en" / 'en'). Catalog
+    # keys are unquoted (`en:`), so searching for the quoted form naturally skips catalog interiors
+    # and matches array/param/enumeration usage - exactly the leads we want.
+    alt=""
+    for c in $EXISTING_CODES; do
+        [ -z "$alt" ] && alt="$c" || alt="$alt|$c"
+    done
+    PATTERN="[\"']($alt)[\"']"
+
+    # Two backends, one interface (mirrors find_candidates.sh): prefer ripgrep, fall back to POSIX
+    # grep. Restrict to the .ts/.tsx universe and exclude tests / .d.ts.
+    if command -v rg >/dev/null 2>&1; then
+        SEARCH() { rg -n --no-heading -g '*.ts' -g '*.tsx' -g '!**/tests/**' -g '!**/*.d.ts' -g '!**/*.test.*' "$@"; }
+    else
+        SEARCH() { grep -rnE --include='*.tsx' --include='*.ts' "$@" | grep -vE '/tests/|\.d\.ts|\.test\.'; }
+    fi
+
+    # Drop the config file (it is meant to name every code) and comment/import lines.
+    DENOISE() {
+        if [ -n "$CONFIG_FILE" ]; then
+            grep -vF "$CONFIG_FILE" | grep -vE '^[^:]*:[0-9]+:[[:space:]]*(//|\*|/\*)'
+        else
+            grep -vE '^[^:]*:[0-9]+:[[:space:]]*(//|\*|/\*)'
+        fi
+    }
+
+    leads="$(SEARCH -e "$PATTERN" "$ROOT" 2>/dev/null | DENOISE || true)"
+    if [ -n "$leads" ]; then
+        printf '%s\n' "$leads"
+    else
+        echo "   (no hardcoded locale-code literals found - locales likely derive from i18n.list)"
+    fi
+    [ -z "$CONFIG_FILE" ] && echo "   NOTE: pass CONFIG_FILE=<path to the I18n config> to drop its expected self-matches."
+fi
+
+echo
+echo "== done. Confirm every lead by reading the file against reference/translation-rules.md. =="