@djangocfg/i18n 2.1.585 → 2.1.590

package/README.md

@@ -53,6 +53,19 @@ import { I18nProvider, useT } from '@djangocfg/i18n'
 | `@djangocfg/i18n/locales` | Locale data only (server-safe) |
 | `@djangocfg/i18n/utils` | Utilities like `mergeTranslations` (server-safe) |
 
+## Self-contained copy
+
+Widgets ship their own typed dictionaries and share one locale contract:
+
+```ts
+import { createCopy, type Locale } from '@djangocfg/i18n/copy'
+
+const DICTIONARIES: Record<Locale, MyCopy> = { en, ru, /* ... */ 'pt-BR': ptBR }
+export const useMyCopy = createCopy(DICTIONARIES).useCopy
+```
+
+See [`@docs/SELF_CONTAINED_COPY.md`](./@docs/SELF_CONTAINED_COPY.md).
+
 ## CLI
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/i18n",
-  "version": "2.1.585",
+  "version": "2.1.590",
   "description": "Lightweight i18n library for @djangocfg packages with built-in translations for English, Russian, and Korean",
   "keywords": [
     "i18n",
@@ -41,6 +41,14 @@
       "import": "./src/locales/index.ts"
     },
     "./locales/*": "./src/locales/*.ts",
+    "./copy": {
+      "types": "./src/copy/index.ts",
+      "import": "./src/copy/index.ts"
+    },
+    "./copy/testing": {
+      "types": "./src/copy/testing.ts",
+      "import": "./src/copy/testing.ts"
+    },
     "./utils": {
       "types": "./src/utils/index.ts",
       "import": "./src/utils/index.ts"
@@ -53,6 +61,7 @@
   "files": [
     "dist",
     "src",
+    "@docs",
     "README.md",
     "LICENSE"
   ],
@@ -75,7 +84,7 @@
     "jiti": "^2.7.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.585",
+    "@djangocfg/typescript-config": "^2.1.590",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",
     "eslint": "^9.39.5",

package/src/copy/createCopy.ts

@@ -0,0 +1,41 @@
+import { useMemo } from 'react'
+
+import { useLocaleOptional } from '../context'
+import { resolveLocale, type Dictionaries, type Locale } from './locales'
+
+export interface CopyKit<T> {
+  /** Every bundled dictionary, for tests and tooling. */
+  readonly dictionaries: Dictionaries<T>
+  /** The dictionary for a language tag; English when it is not bundled. */
+  resolve(tag: string | null | undefined): T
+  /**
+   * The dictionary for the active language: the `locale` prop when the host
+   * passes one, else the `@djangocfg/i18n` provider, else English. With no
+   * provider (a story, a test) it renders without one.
+   */
+  useCopy(locale?: string): T
+  /** The bundled locale `useCopy` resolved to; feed it to `plural()`. */
+  useLocale(locale?: string): Locale
+}
+
+/**
+ * Wire a package's own dictionaries to the shared locale contract.
+ *
+ * The package keeps its strings and its `XCopy` schema; this supplies the one
+ * resolver and the one hook, so locale handling is identical everywhere.
+ */
+export function createCopy<T>(dictionaries: Dictionaries<T>): CopyKit<T> {
+  const resolve = (tag: string | null | undefined): T => dictionaries[resolveLocale(tag)]
+
+  function useLocale(locale?: string): Locale {
+    const fromProvider = useLocaleOptional()
+    return resolveLocale(locale ?? fromProvider)
+  }
+
+  function useCopy(locale?: string): T {
+    const resolved = useLocale(locale)
+    return useMemo(() => dictionaries[resolved], [resolved])
+  }
+
+  return { dictionaries, resolve, useCopy, useLocale }
+}

package/src/copy/format.ts

@@ -0,0 +1,50 @@
+/** The plural categories `Intl.PluralRules` can report; only `other` is required. */
+export interface PluralCopy {
+  readonly zero?: string
+  readonly one?: string
+  readonly two?: string
+  readonly few?: string
+  readonly many?: string
+  readonly other: string
+}
+
+export type FillValues = Readonly<Record<string, string | number>>
+
+/**
+ * Fill `{{name}}` placeholders. The placeholder belongs to the dictionary, so a
+ * translator can move it; a template literal at the call site could not.
+ */
+export function fill(template: string, values: FillValues): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (whole, key: string) => {
+    const value = values[key]
+    return value === undefined ? whole : String(value)
+  })
+}
+
+// Building a PluralRules costs a locale-data lookup and plurals render often.
+const rules = new Map<string, Intl.PluralRules>()
+
+function rulesFor(language: string): Intl.PluralRules {
+  const cached = rules.get(language)
+  if (cached) return cached
+  let made: Intl.PluralRules
+  try {
+    made = new Intl.PluralRules(language)
+  } catch {
+    // An invalid tag throws; a wrong plural beats a crashed render.
+    made = new Intl.PluralRules('en')
+  }
+  rules.set(language, made)
+  return made
+}
+
+/** Pick the plural form for `count` and fill `{{count}}`; `other` is the fallback. */
+export function plural(
+  copy: PluralCopy,
+  count: number,
+  language: string,
+  values: FillValues = {},
+): string {
+  const template = copy[rulesFor(language).select(count)] ?? copy.other
+  return fill(template, { ...values, count })
+}

package/src/copy/index.ts

@@ -0,0 +1,3 @@
+export { LOCALES, resolveLocale, type Dictionaries, type Locale } from './locales'
+export { createCopy, type CopyKit } from './createCopy'
+export { fill, plural, type FillValues, type PluralCopy } from './format'

package/src/copy/locales.ts

@@ -0,0 +1,46 @@
+/**
+ * The locales a self-contained package ships a dictionary for.
+ *
+ * One list for every widget: a package that forgets a language fails `tsc`
+ * (see `Dictionaries`) instead of quietly rendering English for it.
+ */
+export const LOCALES = [
+  'en', 'ru', 'ko', 'ja', 'de', 'fr', 'zh', 'it', 'es',
+  'nl', 'ar', 'tr', 'pl', 'sv', 'no', 'da', 'pt-BR',
+] as const
+
+export type Locale = (typeof LOCALES)[number]
+
+/**
+ * A complete set of dictionaries. `Record` over the closed `Locale` union, so
+ * a missing language is a type error at the registry, not a runtime miss.
+ */
+export type Dictionaries<T> = Readonly<Record<Locale, T>>
+
+/** Language tags hosts report that name one of our locales under another code. */
+const ALIASES: Readonly<Record<string, Locale>> = {
+  nb: 'no',
+  nn: 'no',
+  pt: 'pt-BR',
+  'pt-pt': 'pt-BR',
+}
+
+const BY_LOWER = new Map<string, Locale>(LOCALES.map((l) => [l.toLowerCase(), l]))
+
+/**
+ * Map whatever language tag the host reports to a bundled locale.
+ *
+ * Exact match, then the base language (`zh-CN` → `zh`), then an alias
+ * (`nb` → `no`), then English. One resolver for every package, so two widgets
+ * on one page never disagree about what `pt` means.
+ */
+export function resolveLocale(tag: string | null | undefined): Locale {
+  if (!tag) return 'en'
+  const lower = tag.replace('_', '-').toLowerCase()
+  const exact = BY_LOWER.get(lower)
+  if (exact) return exact
+  const alias = ALIASES[lower]
+  if (alias) return alias
+  const base = lower.split('-')[0] ?? ''
+  return BY_LOWER.get(base) ?? ALIASES[base] ?? 'en'
+}

package/src/copy/testing.ts

@@ -0,0 +1,79 @@
+import { readdirSync } from 'node:fs'
+
+import { LOCALES } from './locales'
+
+type Tree = { readonly [key: string]: string | Tree }
+
+function leaves(tree: Tree, prefix = ''): Map<string, string> {
+  const out = new Map<string, string>()
+  for (const [key, value] of Object.entries(tree)) {
+    const path = prefix ? `${prefix}.${key}` : key
+    if (typeof value === 'string') out.set(path, value)
+    else for (const [p, v] of leaves(value, path)) out.set(p, v)
+  }
+  return out
+}
+
+const placeholders = (s: string): string =>
+  [...s.matchAll(/\{{1,2}(\w+)\}{1,2}/g)].map((m) => m[1]).sort().join(',')
+
+// A language has the plural forms it has (`ko` has no `one`, `ru` adds `few`
+// and `many`), so only `other` is a fixed key under a `PluralCopy`.
+const OPTIONAL_FORMS = new Set(['zero', 'one', 'two', 'few', 'many'])
+const isOptionalForm = (path: string): boolean => OPTIONAL_FORMS.has(path.split('.').pop() ?? '')
+
+const norm = (s: string): string => s.replace('-', '').toLowerCase()
+
+/**
+ * What `tsc` cannot check about a package's dictionaries; returns problems,
+ * empty when clean:
+ *
+ * - the registry covers every locale in `LOCALES`;
+ * - every file in `localesDir` is registered (written, never wired in);
+ * - every dictionary has the same keys as English (plural forms other than
+ *   `other` may differ per language);
+ * - every string is non-blank and keeps the `{{placeholders}}` English has.
+ *
+ * `dictionaries` is typed loosely so any `XCopy` can be passed without a cast.
+ */
+export function checkDictionaries(
+  dictionaries: Readonly<Record<string, object>>,
+  localesDir: string,
+): string[] {
+  const problems: string[] = []
+  const registered = Object.keys(dictionaries)
+
+  for (const locale of LOCALES) {
+    if (!registered.includes(locale)) problems.push(`locale not registered: ${locale}`)
+  }
+
+  const onDisk = readdirSync(localesDir)
+    .filter((n) => n.endsWith('.ts'))
+    .map((n) => n.replace(/\.ts$/, ''))
+  if (onDisk.length === 0) problems.push(`no dictionary files in ${localesDir}`)
+  for (const file of onDisk) {
+    if (!registered.some((k) => norm(k) === norm(file))) {
+      problems.push(`file not registered: ${file}`)
+    }
+  }
+
+  const en = dictionaries.en
+  if (!en) return [...problems, 'no English dictionary']
+  const reference = leaves(en as Tree)
+  for (const [locale, dict] of Object.entries(dictionaries)) {
+    const own = leaves(dict as Tree)
+    for (const [path, text] of reference) {
+      const got = own.get(path)
+      if (got === undefined) {
+        if (!isOptionalForm(path)) problems.push(`${locale}: missing ${path}`)
+      } else if (got.trim() === '') problems.push(`${locale}: blank ${path}`)
+      else if (placeholders(got) !== placeholders(text)) {
+        problems.push(`${locale}: placeholders differ at ${path}`)
+      }
+    }
+    for (const path of own.keys()) {
+      if (!reference.has(path) && !isOptionalForm(path)) problems.push(`${locale}: extra ${path}`)
+    }
+  }
+  return problems
+}