@edgekits/astro-i18n 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,7 +4,26 @@ 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.0 — unreleased
+## 0.1.2 — 2026-10-13
+
+### Fixed
+
+- `package.json` is normalised (`bin` path without `./`, `repository.url` in the `git+https://….git` form), so `npm publish` prints no warnings.
+- The build removes `dist/` before compiling, so a deleted source file can no longer ship as a stale `dist/*.js`.
+
+## 0.1.1 — 2026-10-13
+
+### Changed
+
+- `countryCode` in `languages` is optional. `LanguageSwitcher` renders the `flag` component only for a locale that has one; the item then shows the name alone.
+- The `astro-i18n` skill asks whether to show flags (each locale's `countryCode`, SVGs from the `flag-icons` package or the project's own) and moves the project's pages under `src/pages/[lang]/` during adoption.
+
+### Added
+
+- "Using the skill": a user guide for the `astro-i18n` skill, the same section in this README and in the plugin's.
+- A `prepublishOnly` script that builds `dist/` before `npm publish`.
+
+## 0.1.0 — 2026-10-12
 
 ### Added
 

package/README.md

@@ -73,18 +73,22 @@ export default defineI18nConfig({
 })
 ```
 
-| Field                      | Required | Default      | Meaning                                                                  |
-| -------------------------- | -------- | ------------ | ------------------------------------------------------------------------ |
-| `languages`                | yes      |              | `{ [locale]: { countryCode, name } }`; `countryCode` is for your flag UI |
-| `defaultLocale`            | yes      |              | one of `languages`; its JSON files define the schema                     |
-| `cookie`                   | yes      |              | `{ name, maxAge }` (seconds) of the language cookie                      |
-| `keyPrefix`                | yes      |              | KV keys are `<keyPrefix>:<namespace>:<locale>`                           |
-| `missingTranslationBanner` | yes      |              | enables `MissingTranslationBanner`                                       |
-| `routing`                  | yes      |              | `'prefix'`                                                               |
-| `localesDir`               | no       | `'locales'`  | where the CLI reads `<locale>/<namespace>.json`                          |
-| `generatedDir`             | no       | `'src/i18n'` | where the CLI writes `runtime-constants.ts` and `fallbacks.generated.ts` |
-| `countryToLocale`          | no       | none         | geo-IP step of the locale fallback (see Reference)                       |
-| `markdownLocale`           | no       | none         | the locale `.md` endpoints are served in (see Reference)                 |
+| Field                      | Required | Default      | Meaning                                                                                                  |
+| -------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------- |
+| `languages`                | yes      |              | `{ [locale]: { name, countryCode? } }`; `countryCode` is optional: the code your flag component receives |
+| `defaultLocale`            | yes      |              | one of `languages`; its JSON files define the schema                                                     |
+| `cookie`                   | yes      |              | `{ name, maxAge }` (seconds) of the language cookie                                                      |
+| `keyPrefix`                | yes      |              | KV keys are `<keyPrefix>:<namespace>:<locale>`                                                           |
+| `missingTranslationBanner` | yes      |              | enables `MissingTranslationBanner`                                                                       |
+| `routing`                  | yes      |              | `'prefix'`                                                                                               |
+| `localesDir`               | no       | `'locales'`  | where the CLI reads `<locale>/<namespace>.json`                                                          |
+| `generatedDir`             | no       | `'src/i18n'` | where the CLI writes `runtime-constants.ts` and `fallbacks.generated.ts`                                 |
+| `countryToLocale`          | no       | none         | geo-IP step of the locale fallback (see Reference)                                                       |
+| `markdownLocale`           | no       | none         | the locale `.md` endpoints are served in (see Reference)                                                 |
+
+Locale codes (the keys of `languages`) are lowercase everywhere: the config, the `locales/`
+folders and the URLs (`pt-br`, not `pt-BR`). `toIetfTag()` from `./format` gives the IETF form
+(`pt-BR`) where one is needed, such as `<html lang>` and hreflang.
 
 The config is validated when it loads: an empty `languages`, a `defaultLocale` or
 `markdownLocale` outside it, or a bad `countryToLocale` entry throws with a message naming the
@@ -379,6 +383,265 @@ language-switcher > div {
 }
 ```
 
+#### Flags
+
+The package ships no flag images. To show flags in the switcher, pass your own Astro component
+as `flag`: each item renders it as `<Flag code={countryCode} size={16} />` before the language
+name. A locale without a `countryCode` gets the name alone, and so does every locale when you
+pass no `flag`. A recipe that copies only the SVGs your locales use from the `flag-icons` npm
+package is under [Flags in the switcher](#flags-in-the-switcher) in "Using the skill".
+
+<!-- skill-guide:start -->
+
+## Using the skill
+
+`astro-i18n` is a free agent skill that sets up `@edgekits/astro-i18n` in your project and keeps
+working with it afterwards. It runs in Claude Code as a plugin, and in Cursor, OpenCode or any other
+coding agent that reads `SKILL.md`. Its source is in
+[`plugins/astro-i18n`](https://github.com/EdgeKits/astro-i18n/tree/main/plugins/astro-i18n).
+
+### What it does
+
+The skill adopts `@edgekits/astro-i18n` in an existing Astro project that runs on Cloudflare
+Workers through `@astrojs/cloudflare`. It asks the questions only you can answer, follows the
+package README in order, and checks the result against a checklist. After the setup it handles
+the follow-up work: new keys, locales and namespaces, production copy, localized forms and
+multilingual SEO.
+
+It does not create an Astro project, and it stops if the project has no Cloudflare adapter: the
+package depends on Workers KV. It copies no engine code into your project; everything it writes
+uses the package's exports.
+
+What changes in your project during the setup:
+
+- dependencies: `@edgekits/astro-i18n`, and `flag-icons` as a dev dependency if you want flags;
+- `astro.config`: the `edgekitsI18n()` integration;
+- `wrangler.jsonc`: a `TRANSLATIONS` KV binding;
+- new files: `edgekits-i18n.config.ts`, `locales/<locale>/*.json`, the generated files, and a
+  `Flag.astro` with its SVGs;
+- `src/pages/`: your pages move under `src/pages/[lang]/`;
+- your base layout: `<html lang>` from the request's locale, hreflang tags, the language
+  switcher.
+
+### Installing it
+
+In Claude Code, add the EdgeKits marketplace once, then install the plugin:
+
+```
+/plugin marketplace add EdgeKits/skills
+/plugin install astro-i18n@edgekits
+```
+
+That installs it for you, in every project. To set it up for everyone working on one
+repository, run these in the repository and commit `.claude/settings.json`:
+
+```sh
+claude plugin marketplace add EdgeKits/skills --scope project
+claude plugin install astro-i18n@edgekits --scope project
+```
+
+The first command declares the EdgeKits marketplace in `.claude/settings.json`; the second
+turns the plugin on there, under `enabledPlugins` (`"astro-i18n@edgekits": true`). Claude Code
+honours those entries for a teammate once they trust the folder, but it does not download the
+plugin for them: each teammate runs the same `claude plugin install … --scope project` once.
+
+Any other agent, with the [skills CLI](https://skills.sh):
+
+```sh
+npx skills add EdgeKits/astro-i18n --skill astro-i18n
+```
+
+### Prerequisites
+
+- An Astro `^7.3` project with `output: 'server'` and the `@astrojs/cloudflare` adapter `^14.3`.
+  For a new site: `npm create astro@latest`, then `npx astro add cloudflare`, then set
+  `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 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.
+
+### First run on a fresh site
+
+#### What to say
+
+Open the project in your agent and ask for the result you want, for example:
+
+- "Add i18n to this site: English as the default, German and Brazilian Portuguese."
+- "Make the site multilingual with en and es, and send visitors from Spain and Mexico to
+  Spanish."
+- "Install @edgekits/astro-i18n and set it up."
+
+#### The questions it asks
+
+The skill asks before it writes any code, and waits for the answers:
+
+| Question                                                                     | Example answer                                |
+| ---------------------------------------------------------------------------- | --------------------------------------------- |
+| Which locales, and which is the default?                                     | `en` (default), `de`, `pt-br`                 |
+| Does the site serve markdown endpoints (`/blog/x.md`)? In which locale?      | No (or: yes, `en`)                            |
+| Should a visitor's country pick the locale when nothing else does? How?      | `DE`, `AT`, `CH` → `de`; `BR` → `pt-br`       |
+| Middleware: registered by the integration (`auto`), or in your own sequence? | `auto`                                        |
+| Flags in the language switcher?                                              | Yes: `en` → `us`, `de` → `de`, `pt-br` → `br` |
+
+For flags, a regional locale takes its region (`pt-br` → `br`, `en-gb` → `gb`), and for a
+language-only locale the skill proposes the obvious country (`en` → `us`) for you to confirm. It
+shows the full list back before it writes the config. If you have no preference on any of
+these, it uses the defaults: no geo table, no markdown locale, `auto` middleware, flags on.
+
+#### What it creates
+
+- `edgekits-i18n.config.ts` with your answers, and the integration in `astro.config`.
+- `locales/<default>/common.json` and `messages.json` (the banner texts and form error codes),
+  and the same files for each other locale.
+- The generated files, written by `npx edgekits-i18n seed`: `i18n-data.json`,
+  `src/i18n.generated.d.ts`, `src/i18n/runtime-constants.ts`, `src/i18n/fallbacks.generated.ts`.
+  Commit them.
+- The route layout: `src/pages/about.astro` becomes `src/pages/[lang]/about.astro`, and so on.
+  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).
+- 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
+  shape before it runs wrangler.
+
+#### Flags in the switcher
+
+The package ships no flag images; `LanguageSwitcher` takes your flag component as its `flag`
+prop and passes it each locale's `countryCode`. The skill's recipe, which you can also follow by
+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:
+
+   ```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
+   ```
+
+3. Add `src/components/Flag.astro`:
+
+   ```astro
+   ---
+   import type { SvgComponent } from 'astro/types'
+
+   interface Props {
+     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" />}
+   ```
+
+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.
+
+#### How it checks the result
+
+Before it reports back, the skill runs its adoption checklist: the config matches your answers
+and every locale code is lowercase; `seed` writes the generated files and leaves
+`.i18n-hashes.json` alone; `astro check` passes; under `astro dev`, `/` redirects to a locale,
+each locale renders its own copy (or the default locale's, if it has no JSON yet), an unknown
+first segment such as `/zz/` is prefixed rather than crashing, `<html lang>` reads `pt-BR` on a
+`pt-br` page, hreflang tags cover every locale plus `x-default`, and the switcher changes the
+URL and sets the language cookie. It also checks that no page is left at `src/pages/*.astro`
+and that every `countryCode` has its SVG.
+
+### Everyday work
+
+Ask in plain words: "add a key for the footer note", "add French", "add a `pricing`
+namespace", "change the hero title in production". What the skill does:
+
+- **A key or a value.** It adds a new key to the default locale first, since the default
+  locale's JSON is the type schema, then to the other locales, and runs `npx edgekits-i18n
+seed`. A key that exists only in another locale is not typed.
+- **A locale.** It adds the locale to `languages` (and its SVG, with flags on), optionally
+  writes `locales/<new>/`, runs `seed` and restarts the dev server. A locale without JSON is
+  routable already: it shows the default locale's copy and the missing-translation banner.
+- **A namespace.** It creates `locales/<default>/<namespace>.json` and the same file in each
+  other locale, runs `seed`, and fetches the namespace only on the pages that render it.
+- **Production copy.** Edit the JSON, then: `seed` and check it locally; run the project's
+  checks (`astro check`, tests, build); `npx edgekits-i18n migrate`, which pushes to production
+  KV and purges only the changed namespaces; commit the JSON together with
+  `.i18n-hashes.json`. No redeploy is needed unless the config or code changed too.
+
+`.i18n-hashes.json` records what production KV holds. Only a successful `migrate` writes it,
+it is committed right after, and nothing else edits it. `migrate` refuses to run while that
+file has uncommitted changes.
+
+### Forms and SEO
+
+**Forms.** Ask for "a localized contact form with name, email and message", or "localize this
+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.
+
+**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
+code, using the package's locale constants and helpers: a `SeoHreflangs` component and
+`<html lang>` in the base layout, `sitemap.xml`, `[lang]/rss.xml`, `llms.txt` and `robots.txt`
+endpoints.
+
+### Rules the agent follows
+
+- Locale codes are lowercase everywhere: config keys, `locales/` folders, URLs (`pt-br`). Only
+  `toIetfTag()` produces `pt-BR`, for `<html lang>` and hreflang.
+- Generated files (`*.generated.*`, `runtime-constants.ts`, `i18n-data.json`) come from the CLI
+  and are never edited by hand.
+- `@edgekits/astro-i18n/runtime` and `/middleware` run only in workerd. Anything Node loads
+  (`astro.config`, `src/content.config.ts`, unit tests) uses the Node-safe `/config` and
+  `/format` entries instead.
+- No engine code is copied into the project. If the package lacks something, the skill says so
+  rather than re-implementing it.
+- Secrets (`.dev.vars`, `.env*`, API tokens) never enter git, and anything that touches your
+  Cloudflare account is asked first.
+
+### Troubleshooting
+
+- **Edited translations do not show under `astro dev`.** The local Cache API keeps the first
+  value it served. Put `I18N_CACHE=off` in `.dev.vars`, restart the dev server, run `seed`.
+- **A new key is a type error.** It was added only to a non-default locale, or the CLI has not
+  run since. Add it to the default locale and run `seed` (or `bundle`); if the editor still
+  shows the error, restart its TypeScript server.
+- **`Cannot find module 'cloudflare:workers'` in `tsc`.** Run `npx wrangler types`.
+- **`migrate` refuses to run.** `.i18n-hashes.json` has uncommitted changes. If the last
+  `migrate` wrote it, commit it. If anything else changed it, discard the change with
+  `git checkout .i18n-hashes.json` and run `migrate` again. Never edit or delete it to get
+  past the check.
+- **`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.
+- **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/ }`.
+
+### Privacy
+
+This plugin collects, stores and sends no data. It contains no code, no hooks and no MCP servers, only
+instructions (`SKILL.md`, its reference pages and two starter translation files). The commands it asks your agent
+to run (`npm install`, `wrangler`, the package's `edgekits-i18n` CLI) talk to npm and to your own Cloudflare account
+under their own terms. EdgeKits runs no service behind this plugin.
+
+<!-- skill-guide:end -->
+
 ## How it works
 
 A request reaches the middleware, which settles the URL's locale (redirecting when there is

package/dist/types.d.ts

@@ -4,7 +4,7 @@
  * under plain Node.
  */
 export type I18nLanguage = {
-    countryCode: string;
+    countryCode?: string;
     name: string;
 };
 export type I18nConfig = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgekits/astro-i18n",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -16,7 +16,7 @@
   "author": "Gary Stupak",
   "repository": {
     "type": "git",
-    "url": "https://github.com/EdgeKits/astro-i18n"
+    "url": "git+https://github.com/EdgeKits/astro-i18n.git"
   },
   "homepage": "https://github.com/EdgeKits/astro-i18n#readme",
   "bugs": {
@@ -38,7 +38,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "edgekits-i18n": "./dist/cli/index.js"
+    "edgekits-i18n": "dist/cli/index.js"
   },
   "files": [
     "dist",
@@ -51,7 +51,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
     "test": "node --import ./test/register.mjs --test test/**/*.test.ts",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",

package/src/components/LanguageSwitcher.astro

@@ -5,7 +5,8 @@ import type { Locale } from '../constants'
 
 interface Props {
   // The project's flag component (an Astro component reference), passed in so the
-  // engine imports no project UI. Without it, items render label-only.
+  // engine imports no project UI. It receives the locale's `countryCode`; without the
+  // component, or for a locale without a `countryCode`, the item renders label-only.
   flag?: (props: { code: string; size?: number }) => any
   // The project's icons for the trigger button and the active item (Astro component
   // references, like `flag`). Without them, the minimal inline defaults below render.
@@ -76,7 +77,7 @@ const { uiLocale: currentLang } = Astro.locals
               disabled={isActive}
             >
               <span class={classes.itemLabel}>
-                {Flag && <Flag code={flagCode} size={16} />}
+                {Flag && flagCode && <Flag code={flagCode} size={16} />}
                 {label.name}
               </span>
               {isActive &&

package/src/types.ts

@@ -4,7 +4,9 @@
  * under plain Node.
  */
 
-export type I18nLanguage = { countryCode: string; name: string }
+// `countryCode` is what the switcher's `flag` component receives; without it the item
+// shows the name alone.
+export type I18nLanguage = { countryCode?: string; name: string }
 
 export type I18nConfig = {
   // The only source of truth for languages: the keys are the locales.