saykit 0.12.0 → 0.13.0

package/dist/index.d.mts

@@ -402,8 +402,23 @@ interface Catalogue<Locale extends string = string> {
   /**
    * Matches the best locale from a list of guesses.
    *
+   * Guesses are tried in order, and an earlier guess that matches at all wins
+   * over a later one that would match more closely. Each guess is
+   * canonicalised first, so case does not matter (`en-us` is `en-US`), and
+   * then compared in steps, most specific first:
+   *
+   * 1. The same tag
+   * 2. The same language and script, filling in the script a tag implies, so
+   *    `zh-HK` (Traditional) finds `zh-TW` rather than `zh-CN`
+   * 3. The same language subtag, whole, so `fi` never matches `fil`
+   *
+   * Within a step, the locale written first wins, so with `pt-BR` before
+   * `pt-PT`, `pt` matches `pt-BR`.
+   *
    * An absent or empty guess is skipped rather than throwing, which lets a
    * caller write `match(fromCookie, fromHeader)` without narrowing each first.
+   * So is one that is not a well-formed locale tag, unless it is written
+   * exactly as one of {@link locales}.
    *
    * @param guesses List of locale guesses
    * @returns The best matching locale, or the first of {@link locales} if no

package/dist/index.mjs

@@ -231,6 +231,10 @@ function createCatalogue(messages, options = {}) {
 	const keys = Object.freeze(Object.keys(sources));
 	if (keys.length === 0) throw new Error("A catalogue needs at least one locale, none were given");
 	const locales = keys;
+	const tags = locales.flatMap((locale) => {
+		const tag = parseTag(locale);
+		return tag ? [[locale, tag]] : [];
+	});
 	const store = /* @__PURE__ */ new Map();
 	const views = /* @__PURE__ */ new Map();
 	const loading = /* @__PURE__ */ new Map();
@@ -271,14 +275,15 @@ function createCatalogue(messages, options = {}) {
 			return task;
 		},
 		match(...guesses) {
-			const flat = guesses.flat().filter((guess) => typeof guess === "string" && guess !== "");
-			if (flat.length === 0) return locales[0];
-			for (const guess of flat) {
-				if (locales.includes(guess)) return guess;
-				const prefix = guess.split("-")[0];
-				if (!prefix) continue;
-				const match = locales.find((l) => l.startsWith(prefix));
-				if (match) return match;
+			for (const guess of guesses.flat()) {
+				if (typeof guess !== "string" || guess === "") continue;
+				const tag = parseTag(guess);
+				if (!tag) {
+					if (locales.includes(guess)) return guess;
+					continue;
+				}
+				const found = tags.find(([, t]) => t.canonical === tag.canonical) ?? (tag.script ? tags.find(([, t]) => t.language === tag.language && t.script === tag.script) : void 0) ?? tags.find(([, t]) => t.language === tag.language);
+				if (found) return found[0];
 			}
 			return locales[0];
 		},
@@ -292,6 +297,25 @@ function createCatalogue(messages, options = {}) {
 	}
 	return Object.freeze(catalogue);
 }
+function parseTag(input) {
+	let canonical;
+	try {
+		[canonical] = Intl.getCanonicalLocales(input);
+	} catch {
+		return;
+	}
+	if (!canonical) return void 0;
+	const language = canonical.split("-")[0];
+	let script;
+	try {
+		script = new Intl.Locale(canonical).maximize().script;
+	} catch {}
+	return {
+		canonical,
+		language,
+		script
+	};
+}
 // src/scope.ts
 const NO_VIEW = "No view is in scope for 'say'. Run the work inside 'scope.run(view, callback)', or establish one with 'scope.use(store)'.";
 function createVariableStorage() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saykit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Type-safe i18n library with compile-time macro transforms",
   "keywords": [
     "i18n",

package/skills/saykit/SKILL.md

@@ -97,18 +97,30 @@ module.exports = function (api) {
 };
 ```
 
-A plugin only rewrites macros. Catalogues are never loaded through it: no `next.config` or `metro.config` wrapper, no loader options.
+Next.js and Metro also need `withSayKit` around their config, which compiles the catalogues (see below):
+
+```js
+// next.config.mjs
+import { withSayKit } from 'babel-plugin-saykit/next';
+export default withSayKit({});
+
+// metro.config.js
+const { withSayKit } = require('babel-plugin-saykit/metro');
+module.exports = withSayKit(getDefaultConfig(__dirname));
+```
+
+Catalogues are never loaded through a plugin: no loader options, nothing intercepts an import.
 
 ### Compiled locale modules
 
-`saykit compile` writes a `{locale}.js` beside each catalogue (`src/locales/fr.po` → `src/locales/fr.js`), with the `fallbackLocales` chain already merged in, plus a `{locale}.d.ts` declaring `Record<string, Message>`. `saykit extract` compiles too, and `extract --watch` recompiles when a catalogue changes. Gitignore the `.js` modules and commit the `.d.ts`, which never changes, so `tsc` passes on a fresh clone. Since the modules are not committed, run compile before anything that imports a locale:
+Each catalogue compiles to a `{locale}.js` beside it (`src/locales/fr.po` → `src/locales/fr.js`), with the `fallbackLocales` chain already merged in, plus a `{locale}.d.ts` declaring `Record<string, Message>`. The build plugin does this: `unplugin-saykit` when the build starts, `withSayKit` when Next or Metro loads its config, and both recompile in dev whenever a catalogue changes. `saykit extract` compiles too. Gitignore the `.js` modules and commit the `.d.ts`, which never changes, so `tsc` passes on a fresh clone.
+
+No `pre*` script is needed with a plugin. Without one (plain `babel`, a script Node runs directly), run `saykit compile` before anything imports a locale:
 
 ```json title="package.json"
 {
   "scripts": {
-    "predev": "saykit compile",
-    "prebuild": "saykit compile",
-    "pretest": "saykit compile"
+    "prebuild": "saykit compile"
   }
 }
 ```
@@ -210,7 +222,7 @@ export type Locale = (typeof catalogue.locales)[number];
 
 ```ts
 catalogue.locales; // ['en', 'fr']
-catalogue.match(navigator.languages, cookieLocale); // exact, then language prefix, then locales[0]; nullish guesses are skipped
+catalogue.match(navigator.languages, cookieLocale); // case-insensitive: exact, then language + script, then language, then locales[0]; nullish and malformed guesses are skipped
 catalogue.loaded('fr'); // false until loaded
 const say = await catalogue.load('fr'); // calls the thunk once; synchronous when already loaded
 catalogue.locale('fr'); // synchronous; throws if a lazy locale has not been loaded
@@ -333,7 +345,7 @@ new Client(options, { commands: [new Ping()] }, [new SayPlugin(catalogue)]);
 
 1. Write or change a message.
 2. `saykit extract` (or `saykit extract --watch`). Only the source locale file is written; other locales are created header-only and never touched afterwards. Every locale is then compiled.
-3. Translate the other locales by hand or through a TMS. A locale file needs only the entries actually translated; the rest fall back through `fallbackLocales` to the source string at compile time. After pulling translations, `saykit compile`.
+3. Translate the other locales by hand or through a TMS. A locale file needs only the entries actually translated; the rest fall back through `fallbackLocales` to the source string at compile time. After pulling translations, the next dev server or build compiles them (or `saykit compile` without a plugin).
 4. `saykit clean` when source strings were removed or reworded: it drops orphaned and empty entries from non-source locales and never adds anything.
 
 Commit the catalogues and `.d.ts` files, not the compiled `.js`. CI check that extraction was run:
@@ -353,11 +365,11 @@ Custom formats: a `Formatter` is `{ extension: '.yaml', parse(content) => Messag
 | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | `'say' is a macro and must be used with the relevant saykit plugin` | The file was not transformed. Check the bucket `include` glob and that the plugin is in the bundler and test config |
 | `No message for <id> in locale 'x'`                                 | Stale or hand-written module. Run `saykit extract`; import the compiled file, never declare messages                |
-| `Cannot find module './locales/en.js'`                              | Not compiled yet. `saykit compile`, and add it as a `pre` script                                                    |
+| `Cannot find module './locales/en.js'`                              | Not compiled yet. Add the plugin (and `withSayKit` for Next/Metro), or run `saykit compile` where there is none     |
 | `Messages for locale 'x' have not been loaded yet`                  | `catalogue.locale('x')` on a lazy locale. `await catalogue.load('x')` or `store.set('x')` first                     |
 | `No messages for locale 'x'`                                        | `x` is not a key of the catalogue. Run guesses through `match` first                                                |
 | `'getSay' must be called below a 'withSay'`                         | This segment is not wrapped. Wrap every layout and page, not only the root                                          |
-| Edited a `.po`, dev server shows old strings                        | The module was not recompiled. Run `saykit extract --watch` alongside the dev server, or `saykit compile`           |
+| Edited a `.po`, dev server shows old strings                        | The module was not recompiled. On Next/Metro, check `withSayKit` wraps the config; otherwise run `saykit compile`   |
 | Translator sees `{0}`                                               | Placeholder is not an identifier. Name it: `${{ name: value }}`                                                     |
 | Build fails on a branch key such as `sold-out`                      | ICU keys are identifiers. Rename the discriminant at its source                                                     |
 | `Text strings must be rendered within a <Text> component`           | React Native. `<Say whitespace={false}>`                                                                            |