localization
Implement or extend localization (i18n) for a static, SSR or client-rendered website, or a native app sharing its links, using one canonical pattern — locale-prefixed URLs, locale inferred from a saved choice then the browser/OS languages, a language toggle in the UI, hreflang/SEO, and typed translated strings. Use whenever the user adds a language, translates pages or UI copy, builds or moves a language switcher/toggle, touches Accept-Language or navigator.languages detection, locale redirects or edge middleware, hreflang/og:locale/html lang, per-language routes, slugs, RSS or sitemaps — even if they only say "make this page work in Spanish" or "add an English version".
glrodasz · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add glrodasz/dotfiles --skill localization技能说明
name: localization description: > Implement or extend localization (i18n) for a static, SSR or client-rendered website, or a native app sharing its links, using one canonical pattern — locale-prefixed URLs, locale inferred from a saved choice then the browser/OS languages, a language toggle in the UI, hreflang/SEO, and typed translated strings. Use whenever the user adds a language, translates pages or UI copy, builds or moves a language switcher/toggle, touches Accept-Language or navigator.languages detection, locale redirects or edge middleware, hreflang/og:locale/html lang, per-language routes, slugs, RSS or sitemaps — even if they only say "make this page work in Spanish" or "add an English version".
Localization
One pattern for static sites, SSR apps, client-rendered SPAs and the native apps that share their links. The core (URL scheme, precedence, persistence, toggle behavior) must behave identically in every app. Only the adapters (where detection runs, how the page renders its locale) change per stack.
- Read
references/core-module.mdwhen creating or diffingsrc/i18n/locale.ts. - Read
references/stack-adapters.mdwhen wiring detection, rendering or the toggle. - On a site with theme switching, follow
light-dark-modefor the theme boot script and toggle; this skill only places the language toggle next to it.
Phase 0 — Understand the target
- Existing i18n: grep for an i18n library (
i18next,react-intl,next-intl,vue-i18n, Astroi18nconfig),[lang]/[locale]route folders,Accept-Languageornavigator.languagesreads, locale cookies or localStorage keys, a language switcher, and hreflang tags. Note what each one controls. - Rendering and host: static, SSR or client-rendered SPA, and whether the host runs middleware. This picks the detection adapter (see Where detection runs).
- Locales: the default locale, the other locales, and whether content uses shared or per-language slugs.
- Sibling apps: other apps on the same registrable domain (blog subdomain, native app)
that must share the
localecookie and the/{locale}link shape. - Deviations (existing i18n): list every place the app breaks the rules below
(
?lang=, 301 redirects, a localStorage-only choice, hand-written prefixes, flags, a toggle in the header). Fix the ones you touch, replace the old mechanism instead of running two, and carry the rest into the report.
Phase 1 — Implement
Apply The model and Rules, and why throughout, in this order:
- Core module: see Core module and URL and link arrangement.
- Detection: see Where detection runs.
- Toggle: see Language toggle.
- Strings and formatting: see Strings and formatting.
- Per-language slugs (only when content uses them): see Content with per-language slugs.
- SEO and metadata: see SEO and metadata checklist.
- Testing: see Testing.
When adding a locale to an app that already localizes, follow Adding a locale. For a native app sharing the links, also apply Native apps.
The model
request /about?utm=x
│
├─ path has a locale prefix (/es/…)? ── yes ─► render that locale. Never redirect away.
├─ exempt path (API, assets, dev pages, per-language-slug content)? ── yes ─► render as-is
│
├─ saved choice: cookie `locale` ─┐
├─ else browser/OS: Accept-Language | navigator.languages ├─► target locale
└─ else DEFAULT_LOCALE ─┘
│
└─ target ≠ default ─► 307 / location.replace → /es/about?utm=x
Rules, and why
- The URL is the source of truth for what a page renders. Detection only decides
where an unprefixed first visit lands. A shared
/es/...link must open in Spanish for everyone, and crawlers (no cookie, no Accept-Language) must be able to reach every language. - Default locale unprefixed, every other locale under
/{locale}./about= English,/es/about= Spanish. One deploy, one cookie scope, shareable and crawlable URLs. No?lang=(poorly indexed, lost on copy) and no same-URL content negotiation (breaks caching and sharing). - Precedence: URL → saved choice → browser/OS languages → default. An explicit choice always beats inference, and inference beats a guess.
- Negotiate in the user's priority order. Walk the language list (Accept-Language
sorted by
q, ornavigator.languages) and take the first entry whose base language you support.sv, es;q=0.8→es;en-US, es→en. Looking at only the first entry, or at any entry, both get real users wrong. - Redirect only unprefixed → prefixed, temporarily, preserving
?query#hash. Use 307 (edge) orlocation.replace(client), never 301: the target depends on who's asking, and a cached permanent redirect traps people in the wrong language. Never let a CDN cache the redirect. - Persist the choice in one cookie,
locale. Edge code can read cookies; localStorage is invisible to the edge and scoped to a single origin. SetDomainto the registrable domain so sibling apps (e.g. site + blog subdomain) share one choice. - Any link that switches language persists the choice on
click. Notmousedown: keyboard activation never fires it. - Never hand-write locale prefixes. All internal links go through
localizePath(), and the toggle target comes fromswitchLocalePath(). Duplicated regexes in components drift apart. - Everything locale-specific derives from
pageLocale(pathname):<html lang>,og:locale, hreflang, feeds, date formats, form payloads, 404 page.
URL and link arrangement
| Resource | Default (en) | Other (es) |
|---|---|---|
| Home | / | /es |
| Page with a shared slug | /about | /es/about |
| Content with per-language slugs | /posts/what-is-an-algorithm | /es/posts/que-es-un-algoritmo |