@djangocfg/i18n 2.1.584 → 2.1.586

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/i18n",
-  "version": "2.1.584",
+  "version": "2.1.586",
   "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.584",
+    "@djangocfg/typescript-config": "^2.1.586",
     "@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
+}

package/src/locales/ar.ts

@@ -311,16 +311,6 @@ export const ar: I18nTranslations = {
         anyCodeWorks: "وضع التطوير: أي رمز يعمل",
       },
     },
-    chat: {
-      aiAssistant: "مساعد الذكاء الاصطناعي",
-      defaultTitle: "محادثة الذكاء الاصطناعي",
-      newChat: "محادثة جديدة",
-      closeChat: "إغلاق المحادثة",
-      switchToFloating: "التبديل للوضع العائم",
-      switchToSidebar: "التبديل لوضع الشريط الجانبي",
-      dragToResize: "اسحب لتغيير الحجم",
-      howCanIHelp: "كيف يمكنني مساعدتك؟",
-    },
     pwa: {
       addToHomeScreen: "إضافة للشاشة الرئيسية",
       installApp: "تثبيت التطبيق",

package/src/locales/da.ts

@@ -311,16 +311,6 @@ export const da: I18nTranslations = {
         anyCodeWorks: "Dev-tilstand: Enhver kode virker",
       },
     },
-    chat: {
-      aiAssistant: "AI-assistent",
-      defaultTitle: "AI-chat",
-      newChat: "Ny chat",
-      closeChat: "Luk chat",
-      switchToFloating: "Skift til flydende tilstand",
-      switchToSidebar: "Skift til sidepaneltilstand",
-      dragToResize: "Træk for at ændre størrelse",
-      howCanIHelp: "Hvordan kan jeg hjælpe dig?",
-    },
     pwa: {
       addToHomeScreen: "Tilføj til startskærm",
       installApp: "Installer app",

package/src/locales/de.ts

@@ -311,16 +311,6 @@ export const de: I18nTranslations = {
         anyCodeWorks: "Entwicklermodus: Jeder Code funktioniert",
       },
     },
-    chat: {
-      aiAssistant: "KI-Assistent",
-      defaultTitle: "KI-Chat",
-      newChat: "Neuer Chat",
-      closeChat: "Chat schließen",
-      switchToFloating: "Zu schwebendem Modus wechseln",
-      switchToSidebar: "Zu Seitenleistenmodus wechseln",
-      dragToResize: "Ziehen zum Ändern der Größe",
-      howCanIHelp: "Wie kann ich helfen?",
-    },
     pwa: {
       addToHomeScreen: "Zum Startbildschirm hinzufügen",
       installApp: "App installieren",

package/src/locales/en.ts

@@ -311,16 +311,6 @@ export const en: I18nTranslations = {
         anyCodeWorks: "Dev Mode: Any code works",
       },
     },
-    chat: {
-      aiAssistant: "AI Assistant",
-      defaultTitle: "AI Chat",
-      newChat: "New chat",
-      closeChat: "Close chat",
-      switchToFloating: "Switch to floating mode",
-      switchToSidebar: "Switch to sidebar mode",
-      dragToResize: "Drag to resize",
-      howCanIHelp: "How can I help?",
-    },
     pwa: {
       addToHomeScreen: "Add to Home Screen",
       installApp: "Install App",

package/src/locales/es.ts

@@ -311,16 +311,6 @@ export const es: I18nTranslations = {
         anyCodeWorks: "Modo Dev: Cualquier código funciona",
       },
     },
-    chat: {
-      aiAssistant: "Asistente de IA",
-      defaultTitle: "Chat de IA",
-      newChat: "Nueva conversación",
-      closeChat: "Cerrar chat",
-      switchToFloating: "Cambiar a modo flotante",
-      switchToSidebar: "Cambiar a modo barra lateral",
-      dragToResize: "Arrastra para redimensionar",
-      howCanIHelp: "¿Cómo puedo ayudarte?",
-    },
     pwa: {
       addToHomeScreen: "Agregar a pantalla de inicio",
       installApp: "Instalar aplicación",

package/src/locales/fr.ts

@@ -311,16 +311,6 @@ export const fr: I18nTranslations = {
         anyCodeWorks: "Mode Dev: N'importe quel code fonctionne",
       },
     },
-    chat: {
-      aiAssistant: "Assistant IA",
-      defaultTitle: "Chat IA",
-      newChat: "Nouvelle conversation",
-      closeChat: "Fermer le chat",
-      switchToFloating: "Passer en mode flottant",
-      switchToSidebar: "Passer en mode barre latérale",
-      dragToResize: "Glisser pour redimensionner",
-      howCanIHelp: "Comment puis-je vous aider?",
-    },
     pwa: {
       addToHomeScreen: "Ajouter à l'écran d'accueil",
       installApp: "Installer l'application",

package/src/locales/it.ts

@@ -311,16 +311,6 @@ export const it: I18nTranslations = {
         anyCodeWorks: "Modalità Dev: Qualsiasi codice funziona",
       },
     },
-    chat: {
-      aiAssistant: "Assistente IA",
-      defaultTitle: "Chat IA",
-      newChat: "Nuova chat",
-      closeChat: "Chiudi chat",
-      switchToFloating: "Passa a modalità flottante",
-      switchToSidebar: "Passa a modalità barra laterale",
-      dragToResize: "Trascina per ridimensionare",
-      howCanIHelp: "Come posso aiutarti?",
-    },
     pwa: {
       addToHomeScreen: "Aggiungi alla schermata Home",
       installApp: "Installa l'app",

package/src/locales/ja.ts

@@ -311,16 +311,6 @@ export const ja: I18nTranslations = {
         anyCodeWorks: "開発モード: 任意のコードが有効",
       },
     },
-    chat: {
-      aiAssistant: "AIアシスタント",
-      defaultTitle: "AIチャット",
-      newChat: "新しいチャット",
-      closeChat: "チャットを閉じる",
-      switchToFloating: "フローティングモードに切り替え",
-      switchToSidebar: "サイドバーモードに切り替え",
-      dragToResize: "ドラッグしてサイズ変更",
-      howCanIHelp: "お手伝いできることはありますか？",
-    },
     pwa: {
       addToHomeScreen: "ホーム画面に追加",
       installApp: "アプリをインストール",

package/src/locales/ko.ts

@@ -311,16 +311,6 @@ export const ko: I18nTranslations = {
         anyCodeWorks: "개발 모드: 아무 코드나 사용 가능",
       },
     },
-    chat: {
-      aiAssistant: "AI 어시스턴트",
-      defaultTitle: "AI 채팅",
-      newChat: "새 채팅",
-      closeChat: "채팅 닫기",
-      switchToFloating: "플로팅 모드로 전환",
-      switchToSidebar: "사이드바 모드로 전환",
-      dragToResize: "드래그하여 크기 조절",
-      howCanIHelp: "무엇을 도와드릴까요?",
-    },
     pwa: {
       addToHomeScreen: "홈 화면에 추가",
       installApp: "앱 설치",

package/src/locales/nl.ts

@@ -311,16 +311,6 @@ export const nl: I18nTranslations = {
         anyCodeWorks: "Dev Mode: Elke code werkt",
       },
     },
-    chat: {
-      aiAssistant: "AI-assistent",
-      defaultTitle: "AI Chat",
-      newChat: "Nieuwe chat",
-      closeChat: "Chat sluiten",
-      switchToFloating: "Naar zwevende modus",
-      switchToSidebar: "Naar zijbalkmodus",
-      dragToResize: "Sleep om te vergroten/verkleinen",
-      howCanIHelp: "Hoe kan ik helpen?",
-    },
     pwa: {
       addToHomeScreen: "Toevoegen aan startscherm",
       installApp: "App installeren",

package/src/locales/no.ts

@@ -311,16 +311,6 @@ export const no: I18nTranslations = {
         anyCodeWorks: "Dev-modus: Hvilken som helst kode fungerer",
       },
     },
-    chat: {
-      aiAssistant: "AI-assistent",
-      defaultTitle: "AI-chat",
-      newChat: "Ny chat",
-      closeChat: "Lukk chat",
-      switchToFloating: "Bytt til flytende modus",
-      switchToSidebar: "Bytt til sidefeltmodus",
-      dragToResize: "Dra for å endre størrelse",
-      howCanIHelp: "Hvordan kan jeg hjelpe deg?",
-    },
     pwa: {
       addToHomeScreen: "Legg til på startskjerm",
       installApp: "Installer app",

package/src/locales/pl.ts

@@ -311,16 +311,6 @@ export const pl: I18nTranslations = {
         anyCodeWorks: "Tryb Dev: Każdy kod działa",
       },
     },
-    chat: {
-      aiAssistant: "Asystent AI",
-      defaultTitle: "Chat AI",
-      newChat: "Nowy chat",
-      closeChat: "Zamknij chat",
-      switchToFloating: "Przełącz na tryb pływający",
-      switchToSidebar: "Przełącz na tryb paska bocznego",
-      dragToResize: "Przeciągnij, aby zmienić rozmiar",
-      howCanIHelp: "Jak mogę pomóc?",
-    },
     pwa: {
       addToHomeScreen: "Dodaj do ekranu głównego",
       installApp: "Zainstaluj aplikację",

package/src/locales/pt-BR.ts

@@ -311,16 +311,6 @@ export const ptBR: I18nTranslations = {
         anyCodeWorks: "Modo Dev: Qualquer código funciona",
       },
     },
-    chat: {
-      aiAssistant: "Assistente de IA",
-      defaultTitle: "Chat de IA",
-      newChat: "Nova conversa",
-      closeChat: "Fechar chat",
-      switchToFloating: "Mudar para modo flutuante",
-      switchToSidebar: "Mudar para modo barra lateral",
-      dragToResize: "Arraste para redimensionar",
-      howCanIHelp: "Como posso ajudar?",
-    },
     pwa: {
       addToHomeScreen: "Adicionar à tela inicial",
       installApp: "Instalar aplicativo",

package/src/locales/ru.ts

@@ -311,16 +311,6 @@ export const ru: I18nTranslations = {
         anyCodeWorks: "Режим разработки: подойдёт любой код",
       },
     },
-    chat: {
-      aiAssistant: "AI Ассистент",
-      defaultTitle: "AI Чат",
-      newChat: "Новый чат",
-      closeChat: "Закрыть чат",
-      switchToFloating: "Плавающий режим",
-      switchToSidebar: "Режим боковой панели",
-      dragToResize: "Потяните для изменения размера",
-      howCanIHelp: "Чем могу помочь?",
-    },
     pwa: {
       addToHomeScreen: "На главный экран",
       installApp: "Установить приложение",

package/src/locales/sv.ts

@@ -311,16 +311,6 @@ export const sv: I18nTranslations = {
         anyCodeWorks: "Dev-läge: Vilken kod som helst fungerar",
       },
     },
-    chat: {
-      aiAssistant: "AI-assistent",
-      defaultTitle: "AI-chatt",
-      newChat: "Ny chatt",
-      closeChat: "Stäng chatt",
-      switchToFloating: "Växla till flytande läge",
-      switchToSidebar: "Växla till sidofältsläge",
-      dragToResize: "Dra för att ändra storlek",
-      howCanIHelp: "Hur kan jag hjälpa dig?",
-    },
     pwa: {
       addToHomeScreen: "Lägg till på hemskärmen",
       installApp: "Installera app",

package/src/locales/tr.ts

@@ -311,16 +311,6 @@ export const tr: I18nTranslations = {
         anyCodeWorks: "Geliştirici Modu: Herhangi bir kod çalışır",
       },
     },
-    chat: {
-      aiAssistant: "AI Asistanı",
-      defaultTitle: "AI Sohbet",
-      newChat: "Yeni sohbet",
-      closeChat: "Sohbeti kapat",
-      switchToFloating: "Kayan moda geç",
-      switchToSidebar: "Kenar çubuğu moduna geç",
-      dragToResize: "Yeniden boyutlandırmak için sürükleyin",
-      howCanIHelp: "Size nasıl yardımcı olabilirim?",
-    },
     pwa: {
       addToHomeScreen: "Ana ekrana ekle",
       installApp: "Uygulamayı yükle",

package/src/locales/zh.ts

@@ -311,16 +311,6 @@ export const zh: I18nTranslations = {
         anyCodeWorks: "开发模式：任何验证码都有效",
       },
     },
-    chat: {
-      aiAssistant: "AI 助手",
-      defaultTitle: "AI 聊天",
-      newChat: "新对话",
-      closeChat: "关闭聊天",
-      switchToFloating: "切换到浮动模式",
-      switchToSidebar: "切换到侧边栏模式",
-      dragToResize: "拖动调整大小",
-      howCanIHelp: "有什么可以帮助您的吗？",
-    },
     pwa: {
       addToHomeScreen: "添加到主屏幕",
       installApp: "安装应用",

package/src/types.ts

@@ -409,18 +409,6 @@ export interface I18nTranslations {
       }
     }
 
-    /** MCP Chat */
-    chat: {
-      aiAssistant: string
-      defaultTitle: string
-      newChat: string
-      closeChat: string
-      switchToFloating: string
-      switchToSidebar: string
-      dragToResize: string
-      howCanIHelp: string
-    }
-
     /** PWA Install */
     pwa: {
       /** A2HS Hint */