name: add-i18n\nversion: 2.2.0\ndescription: |\nWire @pracht/i18n: locale-detection middleware (URL prefix, cookie,\nAccept-Language), lazy typed dictionaries, and either strategy —\nlocale-prefixed route groups with hreflang, or one URL per page with a\ncookie-backed switcher.\nUse for \"add i18n\", \"set up translations\", \"make my app multilingual\", \"add\nlocale routing\", \"switch language without changing URLs\", \"extract strings\".\nallowed-tools:
@pracht/i18n ships locale-detection middleware, lazy dictionaries with keys\ntyped from the default locale, t()/tPlural() (plurals via\nIntl.PluralRules), localePath(), and hreflang() for head(). Full guide:\nhttps://pracht.resynapse.dev/docs/recipes/i18n — which also carries a\nhand-rolled fallback recipe if the user refuses the dependency. Working setups\nlive in examples/basic, both locale-prefixed (/welcome, /en/welcome,\n/nl/welcome) and prefix-free (/greeting, src/api/locale.ts).
MCP: when the pracht MCP server is registered (pracht dev-mcp), prefer its\ninspect_routes/inspect_api/inspect_build/doctor/verify/generate_*\ntools over shelling out. pracht inspect needs the pracht plugin in the vite\nconfig.
Use AskUserQuestion once for the supported locales (default en plus one or\ntwo), the default locale, and the URL strategy:
| \n | A. Locale-prefixed (/en/about) | \nB. One URL per page (/about) | \n
|---|---|---|
| Use when | \nPublic, indexable content | \nURLs cannot move, or the app is behind a login | \n
| Locale from | \nThe path | \nThe cookie — switching needs no navigation | \n
| Render modes | \nAny, including ssg/isg | \nssr/spa only (Vary: Cookie, Accept-Language) | \n
| hreflang | \nWorks | \nImpossible — one URL cannot carry alternates | \n
| Cost | \nChanges every URL | \nOne indexed language | \n
Never migrate a live app's URLs without saying so explicitly. Both strategies\ncan coexist in one app. Keep the default detection order\n[\"path\", \"cookie\", \"header\"] either way — the path source simply never\nmatches a prefix-free route — and change it only for an explicit cookie-only\nor header-only request.
npm install @pracht/i18n\n// src/i18n/index.ts\nimport { createDictionaries, defineI18n } from \"@pracht/i18n\";\n\nexport const i18n = defineI18n({ locales: [\"en\", \"fr\"], defaultLocale: \"en\" });\n\nexport type AppLocale = (typeof i18n.locales)[number];\n\nexport const dictionaries = createDictionaries(\n { en: () => import(\"./locales/en.ts\"), fr: () => import(\"./locales/fr.ts\") },\n { defaultLocale: \"en\" },\n);\nOne dictionary module per locale — flat string keys, default export, as const\nso key typing works:
// src/i18n/locales/en.ts\nexport default {\n \"home.title\": \"Welcome, {name}\",\n \"cart.items.one\": \"{count} item\",\n \"cart.items.other\": \"{count} items\",\n} as const;\nPlural keys declare one entry per Intl.PluralRules category the locale needs\n(.one, .other, plus .few/.many for e.g. Polish); tPlural() falls back\nto .other. Non-default locales may omit keys — load() merges the default\nlocale underneath.
// src/middleware/i18n.ts\nimport { i18n } from \"../i18n/index.ts\";\n\nexport const middleware = i18n.middleware;\nIt sets context.locale, persists URL-prefix choices in a SameSite=Lax\ncookie, and appends Vary: Cookie / Accept-Language for whichever sources it\nconsulted. Persistence happens only on per-request (SSR/SPA) routes: SSG/ISG\noutput is stored and replayed to every visitor, so a baked-in Set-Cookie\nwould fail the prerender build and block ISG revalidation. Path-resolved\nSSR/SPA responses still vary on Cookie, because whether they carry that\nSet-Cookie depends on the incoming cookie; path-only SSG/ISG output stays\nkeyed solely by URL. Cookie config stays browser-valid — SameSite=None always\nforces Secure, even if an option tries to disable it.
Type the context once via the Register pattern, intersecting with the app's\nexisting registered context type if it has one:
\n// src/env.d.ts\nimport type { I18nRequestContext } from \"@pracht/i18n\";\n\ndeclare module \"@pracht/core\" {\n interface Register {\n context: I18nRequestContext<\"en\" | \"fr\">;\n }\n}\nOne pathPrefix group per locale, so only registered locales produce URLs and\n/zz/about 404s instead of serving duplicate default-locale content. Never use\na /:locale param route for this — it matches any first segment.
import { defineApp, group, route } from \"@pracht/core\";\n\nconst localizedRoutes = [\n route(\"/\", \"./routes/home.tsx\", { render: \"ssr\" }),\n route(\"/about\", \"./routes/about.tsx\", { render: \"ssr\" }),\n];\n\nexport const app = defineApp({\n middleware: { i18n: \"./middleware/i18n.ts\" },\n routes: [\n group({ middleware: [\"i18n\"] }, [\n group({ pathPrefix: \"/en\" }, localizedRoutes),\n group({ pathPrefix: \"/fr\" }, localizedRoutes),\n route(\"/\", \"./routes/locale-redirect.tsx\", { render: \"ssr\" }),\n ]),\n ],\n});\nThe unprefixed detector redirects using what the middleware resolved. return\nthe redirect — a thrown Response short-circuits past the middleware chain,\nso the i18n middleware could not stamp Vary: Cookie, Accept-Language on it,\nand a shared cache could replay one visitor's locale redirect to everyone:
// src/routes/locale-redirect.tsx\nimport { redirect, type LoaderArgs } from \"@pracht/core\";\nimport { i18n } from \"../i18n/index.ts\";\n\nexport async function loader({ context, request }: LoaderArgs) {\n return redirect(i18n.localePath(\"/\", context.locale), { request });\n}\n\nexport function Component() {\n return null;\n}\nlocalizedRoutes array is fine with auto-generated ids; with\nexplicit ids, each locale's copy needs unique ones.i18n.localePath() so they come out canonical. It resolves literal and\nencoded dot segments before prefixing, so a path assembled from user input\ncannot escape the locale namespace during browser URL normalization.Set-Cookie. In a\nhydrated component shared by those routes, persist the prefix with\nuseEffect(() => { i18n.setLocaleCookie(data.locale); }, [data.locale]) so\nthe SSR detector remembers it later (harmless on SSR pages). Without\nJavaScript, remembering a prerendered visit needs SSR or platform edge\nmiddleware ahead of static asset serving.Nothing about the routes changes: add the middleware to the group, skip the\nprefix groups and the detector route. Detection falls to the cookie, then\nAccept-Language, and the Vary: Cookie, Accept-Language header keeps those\nroutes ssr/spa.
Because no URL prefix ever signals an explicit choice, the switcher writes the\ncookie. Generate an API route so it works with JavaScript disabled:
\n// src/api/locale.ts\nimport { redirect, type BaseRouteArgs } from \"@pracht/core\";\nimport { i18n } from \"../i18n/index.ts\";\n\nfunction sameOriginPath(value: FormDataEntryValue | null, base: URL, fallback: string): string {\n if (typeof value !== \"string\" || !value.startsWith(\"/\")) return fallback;\n try {\n const target = new URL(value, base);\n return target.origin === base.origin\n ? `${target.pathname}${target.search}${target.hash}`\n : fallback;\n } catch {\n return fallback;\n }\n}\n\nexport async function POST({ request, url }: BaseRouteArgs) {\n const form = await request.formData();\n const locale = form.get(\"locale\");\n if (!i18n.isLocale(locale)) return new Response(\"Unknown locale\", { status: 400 });\n\n // Parse `next` before trusting it: URL normalization can expose an origin.\n const target = sameOriginPath(form.get(\"next\"), url, \"/\");\n\n const response = redirect(target, { request, status: 303 });\n response.headers.append(\"set-cookie\", i18n.localeCookie(locale, { url }));\n return response;\n}\nPair it with a <Form method=\"post\" action=\"/api/locale\"> switcher: one\n<button name=\"locale\" value={locale}> per locale plus a hidden next field\ncarrying useLocation().pathname + useLocation().search, so switching does not\ndrop the current query. Hydrated, <Form> uses the framework's redirect\nhandshake and re-runs the loader; without JavaScript the browser follows the\n303.
For an instant switch with no request, i18n.setLocaleCookie(locale) writes the\nsame cookie from the browser and await dictionaries.load(locale) swaps the\ndictionary in place. That path is easy to get wrong — hold the dictionary in\nstate, reset it when loader data changes, and set document.documentElement.lang\nand a localized document.title by hand (head() already ran server-side).\nThen:
useLayoutEffect cleanup keyed by loader\nmessages, so a loader-data change or unmount wins during commit; a passive\nuseEffect cleanup leaves time for a stale import to write its cookie.<Form onSubmit> and before any other navigation that can replace loader\ndata — cleanup at commit cannot undo a stale cookie written mid-transition.i18n.detectClient() is the browser-side detect() when a client-only surface\nmust resolve the locale itself.
import type { HeadArgs, LoaderArgs, RouteComponentProps } from \"@pracht/core\";\nimport { t } from \"@pracht/i18n\";\nimport { dictionaries, i18n } from \"../i18n/index.ts\";\nimport { useEffect } from \"preact/hooks\";\n\nexport async function loader({ context }: LoaderArgs) {\n const messages = await dictionaries.load(context.locale);\n return { locale: context.locale, messages };\n}\n\nexport function head({ data, url }: HeadArgs<typeof loader>) {\n return {\n lang: data.locale,\n title: t(data.messages, \"home.title\"),\n link: i18n.hreflang(url.pathname, { origin: \"https://example.com\" }),\n };\n}\n\nexport function Component({ data }: RouteComponentProps<typeof loader>) {\n // Required for SSG/ISG locale routes; harmless when SSR middleware already\n // persisted the matching path locale.\n useEffect(() => {\n i18n.setLocaleCookie(data.locale);\n }, [data.locale]);\n return <h1>{t(data.messages, \"home.title\", { name: \"Jovi\" })}</h1>;\n}\nmessages is a plain serializable object, so the same t() calls work after\nhydration and on client navigations. hreflang() emits one alternate per\nlocale plus x-default pointing at the unprefixed detector — pass the app's\ncanonical origin. Relative previews stay current-origin because splitLocale()\nkeeps the stripped pathname root-relative, and every alternate preserves an\ninput query/hash suffix. Under strategy B, omit the link entry entirely:\nthere is no alternate URL, so emitting hreflang would be a lie.
lang from the resolved locale in head().ssg/isg —\nevery prefixed URL is a real route, and the middleware skips cookie\npersistence there so no Set-Cookie lands in stored output. Keep \"path\"\nfirst in the detect order for prerendered routes: cookie/header detection\ncannot run against a stored document (prerender/ISG requests carry no cookies\nor Accept-Language), and a route that depends on those sources gets\nVary: Cookie and is refused by the ISG cache.head() runs against a placeholder request origin — pass the\ncanonical origin to hreflang() on SSG/ISG routes instead of url.origin,\nor the alternates bake in http://localhost./audit-seo).Accept-Language resolves to. Say that out loud — if it matters, that is the\nargument for strategy A. Still set lang; sitemap entries stay as-is.Run pracht typegen if step 4 changed route paths or added the API route, and\nadd pracht typegen --check to CI. Boot pracht dev, then:
curl -i the unprefixed detector with Accept-Language: fr\n(302 to /fr/...), with a pracht_locale cookie (cookie beats header), and\nwith garbage (;q=, unknown tags → default locale). On a locale-prefixed\npage, confirm translated content and hreflang links. On SSR, confirm\nSet-Cookie on first visit and Vary: Cookie whether or not the request\ncookie already matches. On SSG/ISG, confirm the stored response has neither\nSet-Cookie nor a path-only Vary, that hydration writes the locale cookie,\nand that the unprefixed detector then returns to that locale. /zz/about\nmust 404.curl -i the page with Accept-Language: fr (French\ncontent, Vary: Cookie, Accept-Language, no Set-Cookie), and with\nCookie: pracht_locale=fr plus Accept-Language: en (cookie wins).\ncurl -i -X POST the switcher with -d locale=fr and an Origin header\nmatching the host (mutation API routes are same-origin-checked): expect 303 +\nSet-Cookie. Post an unregistered locale and an off-origin next: expect\n400 and a same-origin redirect. In the browser, switch and confirm the URL\nnever changes.pnpm test, pnpm e2e, and pracht verify --json all pass.context.locale; loaders read it. Never stash the\nlocale in module-level state — concurrent requests collide.defineI18n/localePath enforce that; never bypass them with string\nconcatenation on user input.Accept-Language handling is already conservative and must stay that way:\nwildcard fallbacks resolve through the registered locale list, explicit\nq=0 exclusions hold against both lookup truncation and best-fit fallback,\ndirectly matched longer variants win before same-language best fit (which\nnever crosses conflicting script subtags), and an entry cut in half by the\ndefensive header-length limit is discarded rather than parsed with an\nimplied quality of 1.getStaticPaths must return the locale ×\ndynamic-param product — prerender only URL combinations that exist.Intl.DateTimeFormat/Intl.NumberFormat and\ndata.locale; no library needed.createDictionaries loaders\nare per-locale lazy imports resolved in loaders — keep them that way.$ARGUMENTS
\n","files":[{"path":"SKILL.md","sizeBytes":15266,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-19T21:17:42.135865Z","sha256":"F26D8032730FAF1ABD01B7C95581771AA07DF8CC95136F91FFBC747B8092D2C7","sizeBytes":6447},"review":null,"source":{"repositoryUrl":"https://github.com/JoviDeCroock/pracht","path":"skills/add-i18n","license":"MIT","commit":"8bcdd52989de3e97708e7f16221839d6313cfdac","subtreeSha":"2E8A79DE3A2DB4DD50DEE441813A2E10FF1C96D54047223BC27EFB14A15706EB","lastSyncedAt":"2026-10-19T21:17:21.911347Z"},"reviewedAt":"2026-10-19T21:18:20.343696Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/JoviDeCroock/pracht/tree/main/skills/add-i18n"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install jovidecroock-pracht@llmmart"},{"target":"git","command":"git clone https://github.com/JoviDeCroock/pracht.git"}]}