@edgekits/astro-i18n 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this package are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package uses
 [Semantic Versioning](https://semver.org/).
 
+## 0.1.3 — 2026-10-13
+
+### Fixed
+
+- The `lang` cookie is no longer `httpOnly`. The `LanguageSwitcher` writes it from the browser and the middleware keeps it in sync with the URL; an `httpOnly` copy set by the server could never be overwritten by the switcher, so a stale value disabled it.
+- A `lang` cookie that is present but not one of the configured locales (a value left by another site on the same host) is set to the URL's locale on the next request. A request without the cookie still gets no `Set-Cookie`.
+
+### Added
+
+- Lists in translation JSON are typed: an array of strings (or an empty one) is `string[]`, an array of objects is `Array<{…}>` from its first element. An array that mixes kinds of elements stops the CLI with an error naming the key. A locale's list replaces the fallback's whole.
+
+### Changed
+
+- The skill's flags recipe serves the SVGs from `public/flags/` through an `<img>` instead of inlining them.
+- The skill treats the island-free form client as the default, not a prohibition: asked for React or a form library, it uses it, with errors as codes and no zod in the browser.
+- "Using the skill": `git init` under Prerequisites; Troubleshooting notes for npm 12's `allowScripts` (`esbuild`, `workerd`) and for a `lang` cookie left by another site on the same host.
+
 ## 0.1.2 — 2026-10-13
 
 ### Fixed

package/README.md

@@ -164,6 +164,9 @@ locales/
 The default locale's files define the schema: their namespaces and keys are the types. Another
 locale may leave keys out; the default locale's text fills the gaps.
 
+Lists are allowed and typed: `["a", "b"]` is `string[]`, a list of objects is `Array<{…}>` from
+its first element, and a locale that has the list replaces it whole.
+
 ### 6. Generate and seed
 
 ```sh
@@ -458,6 +461,9 @@ npx skills add EdgeKits/astro-i18n --skill astro-i18n
   `output: 'server'` in `astro.config`.
 - wrangler `^4.125` installed in the project (`npm i -D wrangler`) and a `wrangler.jsonc`. The
   package's CLI runs the project's own wrangler, never a global one.
+- A git repository (`git init`): the generated files and the purge baseline
+  (`.i18n-hashes.json`) are committed, and `migrate` checks the baseline against git (outside
+  a repository it skips that check, with a warning).
 - A Cloudflare account. Local development needs none until you create the real KV namespace.
 - For `edgekits-i18n migrate` (pushing copy to production): the site on a proxied Cloudflare
   zone (orange cloud), that zone's ID, and an API token with the Zone › Cache Purge permission.
@@ -502,8 +508,8 @@ these, it uses the defaults: no geo table, no markdown locale, `auto` middleware
   The root `index.astro` moves too, since the middleware redirects `/` to `/<locale>/`.
   Endpoints that are not localized (`robots.txt`, `sitemap.xml`, `/api/*`) and `public/` stay
   where they are.
-- `src/components/Flag.astro` and one SVG per flag in `src/assets/icons/flags/`, if you chose
-  flags (the recipe is below).
+- `src/components/Flag.astro` and one SVG per flag in `public/flags/`, if you chose flags (the
+  recipe is below).
 - A KV namespace on your Cloudflare account (`wrangler kv namespace create`). The skill asks
   before it runs that command. Until then, local development works with a placeholder id of 32
   hexadecimal characters, such as `00000000000000000000000000000000`: the CLI checks the id's
@@ -516,37 +522,36 @@ prop and passes it each locale's `countryCode`. The skill's recipe, which you ca
 hand:
 
 1. `npm i -D flag-icons` (MIT).
-2. Copy the SVG of each configured `countryCode`, and only those, into
-   `src/assets/icons/flags/`, and commit them:
+2. Copy the SVG of each configured `countryCode`, and only those, into `public/flags/`, and
+   commit them:
 
    ```sh
-   mkdir -p src/assets/icons/flags
-   for code in us de br; do cp node_modules/flag-icons/flags/4x3/$code.svg src/assets/icons/flags/; done
+   mkdir -p public/flags
+   for code in us de br; do cp node_modules/flag-icons/flags/4x3/$code.svg public/flags/; done
    ```
 
-3. Add `src/components/Flag.astro`:
+3. Add `src/components/Flag.astro`. It serves the file through an `<img>` instead of inlining
+   the SVG: some flag-icons files are large (`es.svg` with its coat of arms is about 80 KB), and
+   an `<img>` is one cached request per flag instead of that markup in every page.
 
    ```astro
    ---
-   import type { SvgComponent } from 'astro/types'
-
+   // src/components/Flag.astro
    interface Props {
-     code: string
+     code?: string
      size?: number
    }
    const { code, size = 16 } = Astro.props
-
-   const flags = import.meta.glob<SvgComponent>('../assets/icons/flags/*.svg', { eager: true, import: 'default' })
-   const Svg = flags[`../assets/icons/flags/${code}.svg`]
    ---
 
-   {Svg && <Svg width={(size * 4) / 3} height={size} aria-hidden="true" />}
+   {code && <img src={`/flags/${code}.svg`} width={(size * 4) / 3} height={size} alt="" loading="lazy" decoding="async" />}
    ```
 
 4. Pass it to the switcher: `<LanguageSwitcher flag={Flag} />`.
 
-A locale without a `countryCode`, or without an SVG, shows its name alone. The flag belongs to
-the `countryCode`, not the language, so `pt` and `pt-br` can show different flags.
+A locale without a `countryCode` shows its name alone. A `countryCode` whose SVG is missing from
+`public/flags/` shows a broken image, so copy one file per code. The flag belongs to the
+`countryCode`, not the language, so `pt` and `pt-br` can show different flags.
 
 #### How it checks the result
 
@@ -587,9 +592,10 @@ file has uncommitted changes.
 form". The skill asks for the fields and their rules, where the form submits (an Astro Action
 by default) and where it renders. What comes back: stable error codes (`INVALID_EMAIL`) with a
 message for every code in every locale's `messages.json`; a server schema that emits the codes;
-an Astro Action; and a `.astro` form with an inline script. The browser side uses no framework
-and no zod: it validates with a small hand-written mirror of the server schema, so the form
-works with a strict Content Security Policy and without JavaScript.
+an Astro Action; and a `.astro` form with an inline script. By default the browser side uses
+no framework and no zod: it validates with a small hand-written mirror of the server schema, so
+the form works with a strict Content Security Policy and without JavaScript. Ask for React or a
+form library and the skill uses it, with the same error codes and still no zod in the browser.
 
 **SEO.** Ask for "hreflang tags", "a sitemap for every locale", "an RSS feed per locale",
 "`llms.txt`" or "`robots.txt` that blocks staging". The skill writes them as your project's
@@ -626,12 +632,27 @@ endpoints.
 - **`migrate` updated KV but the site shows old copy.** The purge was skipped: the zone is not
   proxied, or the zone ID or token is missing. Fix it and run `migrate` again; it retries the
   same purge.
+- **npm 12: `esbuild` or `workerd` did not install.** npm 12 blocks dependency install
+  scripts by default and lists the skipped packages at the end of `npm install`. Both need
+  theirs: run `npm install-scripts approve esbuild workerd`, then
+  `npm rebuild esbuild workerd`. The approval is the `allowScripts` field in `package.json`;
+  `approve` pins the installed versions (`"esbuild@0.28.2": true`), and a name-only entry
+  allows later versions too:
+
+  ```json
+  "allowScripts": { "esbuild": true, "workerd": true }
+  ```
+
+- **The language switcher has no effect (before 0.1.3).** A `lang` cookie from another site on
+  the same host (every `localhost` port shares one set of cookies) could not be overwritten by
+  the switcher. Since 0.1.3 the middleware replaces a `lang` value that is not one of your
+  locales with the URL's locale on the next request, and the switcher can write it again.
 - **Windows.** Local KV (`seed`) can fail with "Network connection lost" or "internal error"
   when the project sits in a deep folder: the local Workers runtime hits the path length
   limit, so keep the project at a short path. Stopping `astro dev` can leave `workerd.exe`
   running and holding `.wrangler/state`; end it before the next `seed`. In PowerShell, copy
   the flags with
-  `foreach ($c in 'us','de','br') { Copy-Item node_modules/flag-icons/flags/4x3/$c.svg src/assets/icons/flags/ }`.
+  `foreach ($c in 'us','de','br') { Copy-Item node_modules/flag-icons/flags/4x3/$c.svg public/flags/ }`.
 
 ### Privacy
 

package/dist/cli/generate.d.ts

@@ -31,7 +31,10 @@ export declare function localesWithTranslations(collected: CollectedData): strin
 export declare function schemaSourceLocale(collected: CollectedData, defaultLocale: string): string | undefined;
 /** `wrangler kv bulk put` input: one entry per locale and namespace. */
 export declare function buildBulkData(collected: CollectedData, keyPrefix: string): KvBulkEntry[];
-/** `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale. */
+/**
+ * `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale.
+ * Throws, naming the key, when an array in it mixes kinds of elements.
+ */
 export declare function buildTypesContent(collected: CollectedData, defaultLocale: string): string;
 /**
  * `runtime-constants.ts`:

package/dist/cli/generate.js

@@ -55,29 +55,56 @@ export function buildBulkData(collected, keyPrefix) {
     }
     return bulkData;
 }
-function generateSchemaTs(schema, indent = 4) {
+function isTree(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// The JSON kind of an array element; an array is typed only when all its elements share one.
+function jsonKind(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * The TS type of one JSON value. Objects become object types; arrays become `string[]`
+ * (strings, other scalars, or empty) or `Array<…>` typed from their first element
+ * (objects, nested arrays); every other leaf stays `string`. `keyPath` and `file` name the
+ * value in the error a mixed array raises.
+ */
+function generateSchemaTs(value, indent, keyPath, file) {
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return 'string[]';
+        const kinds = [...new Set(value.map(jsonKind))];
+        if (kinds.length > 1) {
+            throw new Error(`Key "${keyPath}" (${file}) is an array that mixes ${kinds.join(', ')} elements: ` +
+                'I18n.Schema cannot type it. Use one kind of element per array.');
+        }
+        const first = value[0];
+        if (!isTree(first) && !Array.isArray(first))
+            return 'string[]';
+        return `Array<${generateSchemaTs(first, indent, `${keyPath}[0]`, file)}>`;
+    }
+    if (!isTree(value))
+        return 'string';
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return '{}';
     const pad = ' '.repeat(indent);
     const padInner = ' '.repeat(indent + 2);
-    if (schema && typeof schema === 'object' && !Array.isArray(schema)) {
-        const entries = Object.entries(schema);
-        if (entries.length === 0)
-            return '{}';
-        const lines = entries.map(([key, value]) => {
-            const valueTs = value && typeof value === 'object' && !Array.isArray(value)
-                ? generateSchemaTs(value, indent + 2)
-                : 'string';
-            return `${padInner}${JSON.stringify(key)}: ${valueTs}`;
-        });
-        return `{\n${lines.join(';\n')};\n${pad}}`;
-    }
-    return 'string';
+    const lines = entries.map(([key, child]) => `${padInner}${JSON.stringify(key)}: ${generateSchemaTs(child, indent + 2, `${keyPath}.${key}`, file)}`);
+    return `{\n${lines.join(';\n')};\n${pad}}`;
 }
-/** `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale. */
+/**
+ * `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale.
+ * Throws, naming the key, when an array in it mixes kinds of elements.
+ */
 export function buildTypesContent(collected, defaultLocale) {
     const source = schemaSourceLocale(collected, defaultLocale);
     const schemaObject = (source && collected[source]) || {};
     const namespaceLines = Object.entries(schemaObject).map(([ns, value]) => {
-        const valueTs = generateSchemaTs(value, 10);
+        const valueTs = generateSchemaTs(value, 10, ns, `${source}/${ns}.json`);
         return `      ${JSON.stringify(ns)}: ${valueTs}`;
     });
     const interfaceBody = namespaceLines.length > 0

package/dist/cli/index.js

@@ -82,8 +82,12 @@ async function run(command, args) {
     // 1. Collect translations from <localesDir>/<locale>/<namespace>.json
     // -------------------------------------------------------------------------
     const collected = collectTranslations(localesDir);
+    // The schema is built here too, so an untypeable value (a mixed array) stops the run
+    // before anything is written.
+    let typesContent;
     try {
         assertValidNames(collected, config.languages);
+        typesContent = buildTypesContent(collected, defaultLocale);
     }
     catch (err) {
         console.error(`[i18n] ${err instanceof Error ? err.message : String(err)}`);
@@ -117,7 +121,7 @@ async function run(command, args) {
         console.warn(`[i18n] defaultLocale="${defaultLocale}" has no translation files. ` +
             `Using "${source}" as the source for I18n.Schema.`);
     }
-    writeFile(OUTPUT_TYPES, buildTypesContent(collected, defaultLocale));
+    writeFile(OUTPUT_TYPES, typesContent);
     writeFile(outputRuntimeConstants, buildRuntimeConstantsContent(collected, defaultLocale));
     // -------------------------------------------------------------------------
     // 4. Fallbacks (seed, migrate, or bundle --fallbacks)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgekits/astro-i18n",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Edge-native i18n for Astro on Cloudflare Workers: translations in Workers KV, a per-namespace edge cache invalidated by the Purge API, and typed keys.",
   "keywords": [
     "astro",

package/src/cli/generate.ts

@@ -82,35 +82,65 @@ export function buildBulkData(collected: CollectedData, keyPrefix: string): KvBu
   return bulkData
 }
 
-function generateSchemaTs(schema: TranslationTree, indent = 4): string {
-  const pad = ' '.repeat(indent)
-  const padInner = ' '.repeat(indent + 2)
+function isTree(value: unknown): value is TranslationTree {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
 
-  if (schema && typeof schema === 'object' && !Array.isArray(schema)) {
-    const entries = Object.entries(schema)
-    if (entries.length === 0) return '{}'
+// The JSON kind of an array element; an array is typed only when all its elements share one.
+function jsonKind(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'array'
+  return typeof value
+}
 
-    const lines = entries.map(([key, value]) => {
-      const valueTs =
-        value && typeof value === 'object' && !Array.isArray(value)
-          ? generateSchemaTs(value as TranslationTree, indent + 2)
-          : 'string'
-      return `${padInner}${JSON.stringify(key)}: ${valueTs}`
-    })
+/**
+ * The TS type of one JSON value. Objects become object types; arrays become `string[]`
+ * (strings, other scalars, or empty) or `Array<…>` typed from their first element
+ * (objects, nested arrays); every other leaf stays `string`. `keyPath` and `file` name the
+ * value in the error a mixed array raises.
+ */
+function generateSchemaTs(value: unknown, indent: number, keyPath: string, file: string): string {
+  if (Array.isArray(value)) {
+    if (value.length === 0) return 'string[]'
 
-    return `{\n${lines.join(';\n')};\n${pad}}`
+    const kinds = [...new Set(value.map(jsonKind))]
+    if (kinds.length > 1) {
+      throw new Error(
+        `Key "${keyPath}" (${file}) is an array that mixes ${kinds.join(', ')} elements: ` +
+          'I18n.Schema cannot type it. Use one kind of element per array.',
+      )
+    }
+
+    const first = value[0]
+    if (!isTree(first) && !Array.isArray(first)) return 'string[]'
+    return `Array<${generateSchemaTs(first, indent, `${keyPath}[0]`, file)}>`
   }
 
-  return 'string'
+  if (!isTree(value)) return 'string'
+
+  const entries = Object.entries(value)
+  if (entries.length === 0) return '{}'
+
+  const pad = ' '.repeat(indent)
+  const padInner = ' '.repeat(indent + 2)
+  const lines = entries.map(
+    ([key, child]) =>
+      `${padInner}${JSON.stringify(key)}: ${generateSchemaTs(child, indent + 2, `${keyPath}.${key}`, file)}`,
+  )
+
+  return `{\n${lines.join(';\n')};\n${pad}}`
 }
 
-/** `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale. */
+/**
+ * `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale.
+ * Throws, naming the key, when an array in it mixes kinds of elements.
+ */
 export function buildTypesContent(collected: CollectedData, defaultLocale: string): string {
   const source = schemaSourceLocale(collected, defaultLocale)
   const schemaObject: TranslationTree = (source && collected[source]) || {}
 
   const namespaceLines = Object.entries(schemaObject).map(([ns, value]) => {
-    const valueTs = generateSchemaTs(value as TranslationTree, 10)
+    const valueTs = generateSchemaTs(value, 10, ns, `${source}/${ns}.json`)
     return `      ${JSON.stringify(ns)}: ${valueTs}`
   })
 

package/src/cli/index.ts

@@ -116,8 +116,12 @@ async function run(command: Command, args: string[]): Promise<void> {
 
   const collected = collectTranslations(localesDir)
 
+  // The schema is built here too, so an untypeable value (a mixed array) stops the run
+  // before anything is written.
+  let typesContent: string
   try {
     assertValidNames(collected, config.languages)
+    typesContent = buildTypesContent(collected, defaultLocale)
   } catch (err) {
     console.error(`[i18n] ${err instanceof Error ? err.message : String(err)}`)
     process.exit(1)
@@ -161,7 +165,7 @@ async function run(command: Command, args: string[]): Promise<void> {
     )
   }
 
-  writeFile(OUTPUT_TYPES, buildTypesContent(collected, defaultLocale))
+  writeFile(OUTPUT_TYPES, typesContent)
   writeFile(outputRuntimeConstants, buildRuntimeConstantsContent(collected, defaultLocale))
 
   // -------------------------------------------------------------------------

package/src/components/LanguageSwitcher.astro

@@ -185,8 +185,8 @@ const { uiLocale: currentLang } = Astro.locals
       // Persist the EXPLICIT language choice client-side. The i18n middleware
       // no longer creates the cookie on plain page views (a cookie-less request
       // must stay free of Set-Cookie so the HTML edge cache can serve it), so
-      // the switcher is the place where the preference is born. Not httpOnly —
-      // the server only ever reads it (schema-validated), never trusts it.
+      // the switcher is the place where the preference is born. Not httpOnly on
+      // either side (cookie-storage.ts): the server validates it, never trusts it.
       document.cookie = `${cookieName}=${lang}; path=/; max-age=${cookieMaxAge}; SameSite=Lax; Secure`
 
       window.location.href = this.replaceLocaleInPath(pathname, currentLang, lang)

package/src/cookie-storage.ts

@@ -5,28 +5,43 @@ import { LocaleSchema } from './schema'
 import type { Locale } from './constants'
 import { LANG_COOKIE_NAME } from './constants'
 
-// Self-contained on purpose: the same options and the same invalid-value warning
-// as the project's src/utils/server/cookies.ts, without importing it.
+// The lang cookie is a preference, not a secret, and it has two writers: the
+// LanguageSwitcher's client script (`document.cookie`) and the middleware's URL-wins
+// sync. Hence `httpOnly: false`: an httpOnly copy set here could never be overwritten
+// by the switcher again, and a stale value would disable it for good. The server only
+// reads the value through LocaleSchema, never trusts it. `?.`: plain Node (the tests)
+// has no `import.meta.env`.
 export function setCookieLang(cookies: AstroCookies, locale: Locale) {
   cookies.set(LANG_COOKIE_NAME, locale, {
     path: '/',
-    httpOnly: true,
-    secure: import.meta.env.PROD,
+    httpOnly: false,
+    secure: import.meta.env?.PROD === true,
     sameSite: 'lax',
     maxAge: I18N_CONFIG.cookie.maxAge,
   })
 }
 
-export function getCookieLang(cookies: AstroCookies): Locale | null {
+export type CookieLang = {
+  // A lang cookie came with the request, whatever its value.
+  present: boolean
+  // Its value when it is a supported locale, otherwise null.
+  locale: Locale | null
+}
+
+export function readCookieLang(cookies: AstroCookies): CookieLang {
   const entry = cookies.get(LANG_COOKIE_NAME)
-  if (!entry) return null
+  if (!entry) return { present: false, locale: null }
 
   const result = LocaleSchema.safeParse(entry.value)
-  if (result.success) return result.data
+  if (result.success) return { present: true, locale: result.data }
 
-  if (!import.meta.env.PROD) {
+  if (import.meta.env?.PROD !== true) {
     console.warn(`Invalid cookie "${LANG_COOKIE_NAME}"`, result.error.issues)
   }
 
-  return null
+  return { present: true, locale: null }
+}
+
+export function getCookieLang(cookies: AstroCookies): Locale | null {
+  return readCookieLang(cookies).locale
 }

package/src/middleware/i18n.ts

@@ -2,7 +2,7 @@ import type { MiddlewareHandler } from 'astro'
 import { LocaleSchema } from '../schema'
 import { I18N_CONFIG } from '../config'
 import { DEFAULT_LOCALE, type Locale } from '../constants'
-import { getCookieLang, setCookieLang } from '../cookie-storage'
+import { getCookieLang, readCookieLang, setCookieLang } from '../cookie-storage'
 import { resolveFallbackLocale as resolveFallbackFrom } from '../locale-fallback'
 import { MARKDOWN_PATH, markdownRedirectTarget } from '../markdown-path'
 import { resolveLocaleForTranslations } from '../resolve-locale'
@@ -183,7 +183,7 @@ export const i18nMiddleware: MiddlewareHandler = async (context, next) => {
 
   if (urlLocale) {
     // Keep the lang cookie in sync with the URL locale — but ONLY update an
-    // EXISTING cookie that differs. Rationale (HTML edge cache, P1/P2):
+    // EXISTING cookie that differs or does not parse. Rationale (HTML edge cache, P1/P2):
     //   - The old unconditional set emitted `Set-Cookie` on EVERY localized
     //     response, which made every response uncacheable (the edge cache
     //     refuses anything carrying Set-Cookie).
@@ -193,8 +193,11 @@ export const i18nMiddleware: MiddlewareHandler = async (context, next) => {
     //     created here — the explicit language choice is persisted client-side
     //     by the LanguageSwitcher, and an existing cookie is re-synced below
     //     when the user lands on a different locale by any other means.
-    const cookieLocale = getCookieLang(context.cookies)
-    if (cookieLocale && cookieLocale !== urlLocale) {
+    //   - A cookie that is present but invalid (a foreign value from another site
+    //     on the same host, a locale this site does not have) is corrected to the
+    //     URL locale too, so a stale value never outlives the next request.
+    const cookie = readCookieLang(context.cookies)
+    if (cookie.present && cookie.locale !== urlLocale) {
       setCookieLang(context.cookies, urlLocale)
     }
     // Set uiLocale to Astro locals