@ultimat3/i18n 21.0.0 → 22.0.0

package/README.md

@@ -117,6 +117,15 @@ X_CATALOG_MISSING_KEYS: catalog is incomplete
 | `X_CATALOG_MISSING_KEYS` | a shipped locale lacks a key the source uses |
 | `X_CATALOG_INVALID` | non-string leaf, bad key segment, or a dotted/nested collision |
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `I18nError` | `X_LOCALE_UNSUPPORTED`, `X_CATALOG_MISSING_KEYS`, `X_CATALOG_INVALID`, `X_CATALOG_UNREGISTERED` | `src/errors.ts` |
+
 ## Why it exists
 
 Retrofitting i18n means touching every string in the app. Structuring for many locales on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/i18n",
-  "version": "21.0.0",
+  "version": "22.0.0",
   "description": "Dependency-free translator, catalog flattening, locale negotiation and loud missing-key rendering",
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "21.0.0"
+    "@ultimat3/core": "22.0.0"
   }
 }

package/src/catalogs/en.json

@@ -194,7 +194,8 @@
     "error": {
       "action-failed": "The action threw before it finished.",
       "confirmation-required": "This is destructive: echo the confirmation token first.",
-      "invalid-input": "Some fields did not pass the entity's own schema."
+      "invalid-input": "Some fields did not pass the entity's own schema.",
+      "operation-not-offered": "This resource does not offer that operation."
     },
     "form": {
       "cancel": "Cancel",

package/src/locales.ts

@@ -50,8 +50,18 @@ export const SUPPORTED_LOCALES: readonly Locale[] = [
 export { type Direction, directionOf, isRtl } from '@ultimat3/core';
 
 /**
- * Strip region, lowercase, fall back to the default.
- * `pt-BR` → `pt`; `ZH-Hant-TW` → `zh-hant` when that tag is supported, else `zh`.
+ * The registered spelling of `lower`, compared case-insensitively. A registered `pt-BR` used to
+ * be compared EXACTLY against a request tag this function had just lowercased, so `pt-BR` from a
+ * query, a cookie or a header never matched it and every such request fell back.
+ */
+function registered(lower: string, supported: readonly Locale[]): Locale | undefined {
+  return supported.find((locale) => locale.toLowerCase().replace(/_/g, '-') === lower);
+}
+
+/**
+ * Strip region, match case-insensitively, answer the REGISTERED spelling, fall back to the default.
+ * `pt-BR` → `pt-BR` when that tag is registered, else `pt`; `ZH-Hant-TW` → `zh-hant` (or
+ * `zh-Hant`, as registered) when that tag is supported, else `zh`.
  */
 export function normalizeLocale(
   tag?: string | null,
@@ -61,17 +71,18 @@ export function normalizeLocale(
   if (!tag) return fallback;
   const lower = tag.trim().toLowerCase().replace(/_/g, '-');
   if (lower.length === 0 || lower === '*') return fallback;
-  if (supported.includes(lower)) return lower;
+  const whole = registered(lower, supported);
+  if (whole !== undefined) return whole;
 
   const segments = lower.split('-');
   const primary = segments[0] ?? '';
   // `lang-script` is a distinct written form (zh-hant vs zh-hans) — try it before dropping to `lang`.
   const script = segments[1];
   if (script !== undefined && script.length === 4) {
-    const withScript = `${primary}-${script}`;
-    if (supported.includes(withScript)) return withScript;
+    const withScript = registered(`${primary}-${script}`, supported);
+    if (withScript !== undefined) return withScript;
   }
-  return supported.includes(primary) ? primary : fallback;
+  return registered(primary, supported) ?? fallback;
 }
 
 /** Same as `normalizeLocale` but loud: use where an unknown locale is a caller bug. */