libp2r2p 0.3.0 → 0.4.0

package/README.md

@@ -175,6 +175,60 @@ Use explicit subpath imports for bundle size. The package root re-exports the
 main messenger API for convenience, but applications that only need one piece
 should import that subpath directly.
 
+## Internationalization
+
+The dependency-free `libp2r2p/i18n` subpath exposes locale detection and a
+small translator suitable for keeping each component's translations beside
+that component. Translation keys are literal strings, not dotted paths.
+
+```js
+import { getT } from 'libp2r2p/i18n'
+
+const t = getT({
+  'Allow {{size}}': {
+    en: 'Allow {{size}}',
+    'pt-BR': 'Permitir {{size}}'
+  },
+  'Delete {{count}} items': {
+    en: {
+      one: 'Delete {{count}} item',
+      other: 'Delete {{count}} items'
+    }
+  }
+})
+
+t('Allow {{size}}', { size: '10 MiB' })
+```
+
+`getCurrentDeviceLocale()` prefers the locale resolved by `Intl`, then browser
+language hints, and preserves the full canonical BCP 47 locale. `getT()`
+matches exact and compatible language variants, falls back to English and then
+to the key itself, interpolates `{{name}}` values, and uses `Intl.PluralRules`
+when a locale value supplies plural forms. Missing interpolation values remain
+visible in the returned string.
+
+Catalog validation is opt-in. `validateLocales()` can be used independently,
+or `getT()` can validate once when creating the translator:
+
+```js
+import { getT, validateLocales } from 'libp2r2p/i18n'
+
+const validation = {
+  requiredLocales: ['en', 'pt-BR'],
+  referenceLocale: 'en',
+  requireReferenceKey: true
+}
+
+validateLocales(locales, validation)
+const t = getT(locales, { validation })
+```
+
+Validation checks catalog structure, required locales, plural `other` forms,
+and placeholder parity across every translation. `requireReferenceKey` also
+requires the reference locale's string, or its plural `other` form, to equal
+the literal translation key. Without `validation`, sparse catalogs continue
+to use the normal locale fallback behavior.
+
 ## Binary encodings
 
 Base16, Base36, Base62, Base64/Base64URL, and Base93 helpers are available

package/i18n/index.js

@@ -0,0 +1,235 @@
+const DEFAULT_LOCALE = 'en'
+const INTERPOLATION_RE = /{{\s*([A-Za-z0-9_.-]+)\s*}}/g
+
+function assertLocales (locales) {
+  if (!locales || typeof locales !== 'object' || Array.isArray(locales)) {
+    throw new TypeError('locales should be an object')
+  }
+}
+
+function placeholderSignature (value) {
+  return [...String(value).matchAll(INTERPOLATION_RE)]
+    .map(match => match[1])
+    .sort()
+    .join(',')
+}
+
+function validateTranslationValue (key, locale, value, expectedPlaceholders) {
+  if (typeof value === 'string') {
+    if (placeholderSignature(value) !== expectedPlaceholders) {
+      throw new Error(`placeholder mismatch for "${key}" (${locale})`)
+    }
+    return
+  }
+
+  if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.other !== 'string') {
+    throw new TypeError(`translation for "${key}" (${locale}) should be a string or plural object with an other form`)
+  }
+
+  for (const form of Object.values(value)) {
+    if (typeof form !== 'string') {
+      throw new TypeError(`plural forms for "${key}" (${locale}) should be strings`)
+    }
+    if (placeholderSignature(form) !== expectedPlaceholders) {
+      throw new Error(`placeholder mismatch for "${key}" (${locale})`)
+    }
+  }
+}
+
+export function validateLocales (locales, options = {}) {
+  assertLocales(locales)
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('validation options should be an object')
+  }
+  const {
+    requiredLocales = [],
+    referenceLocale = DEFAULT_LOCALE,
+    requireReferenceKey = false
+  } = options
+  if (!Array.isArray(requiredLocales) || requiredLocales.some(locale => typeof locale !== 'string' || !locale)) {
+    throw new TypeError('requiredLocales should be an array of non-empty strings')
+  }
+  if (typeof referenceLocale !== 'string' || !referenceLocale) {
+    throw new TypeError('referenceLocale should be a non-empty string')
+  }
+
+  for (const [key, translations] of Object.entries(locales)) {
+    if (!translations || typeof translations !== 'object' || Array.isArray(translations)) {
+      throw new TypeError(`translations for "${key}" should be an object`)
+    }
+
+    for (const locale of requiredLocales) {
+      if (!Object.prototype.hasOwnProperty.call(translations, locale)) {
+        throw new Error(`missing translation for "${key}" (${locale})`)
+      }
+    }
+
+    const expectedPlaceholders = placeholderSignature(key)
+    for (const [locale, value] of Object.entries(translations)) {
+      validateTranslationValue(key, locale, value, expectedPlaceholders)
+    }
+
+    if (requireReferenceKey) {
+      if (!Object.prototype.hasOwnProperty.call(translations, referenceLocale)) {
+        throw new Error(`missing reference translation for "${key}" (${referenceLocale})`)
+      }
+      const reference = translations[referenceLocale]
+      const referenceValue = typeof reference === 'string' ? reference : reference.other
+      if (referenceValue !== key) {
+        throw new Error(`reference translation should match key "${key}" (${referenceLocale})`)
+      }
+    }
+  }
+
+  return locales
+}
+
+function canonicalizeLocale (locale) {
+  if (typeof locale !== 'string' || !locale.trim()) return null
+  const value = locale.trim().replace(/_/g, '-')
+  try {
+    return Intl.getCanonicalLocales(value)[0] ?? null
+  } catch {
+    return null
+  }
+}
+
+function getIntlLocale () {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().locale
+  } catch {
+    return null
+  }
+}
+
+function getNavigator () {
+  try {
+    return globalThis.navigator
+  } catch {
+    return null
+  }
+}
+
+export function getCurrentDeviceLocale () {
+  const navigator = getNavigator()
+  const candidates = [
+    getIntlLocale(),
+    navigator?.language,
+    navigator?.languages?.[0],
+    DEFAULT_LOCALE
+  ]
+
+  for (const candidate of candidates) {
+    const locale = canonicalizeLocale(candidate)
+    if (locale) return locale
+  }
+  return DEFAULT_LOCALE
+}
+
+function localeLanguage (locale) {
+  try {
+    return new Intl.Locale(locale).language
+  } catch {
+    return locale.split('-')[0].toLowerCase()
+  }
+}
+
+function preferredChineseLocale (locale) {
+  if (localeLanguage(locale) !== 'zh') return null
+  try {
+    const { script, region } = new Intl.Locale(locale)
+    if (script === 'Hant' || ['TW', 'HK', 'MO'].includes(region)) return 'zh-TW'
+    return 'zh-CN'
+  } catch {
+    return /(?:^|-)(?:hant|tw|hk|mo)(?:-|$)/i.test(locale) ? 'zh-TW' : 'zh-CN'
+  }
+}
+
+function localeCandidates (translations, requestedLocale, fallbackLocale) {
+  const keys = Object.keys(translations)
+  const canonicalKeys = new Map()
+  for (const key of keys) {
+    const canonical = canonicalizeLocale(key)
+    if (canonical && !canonicalKeys.has(canonical.toLowerCase())) {
+      canonicalKeys.set(canonical.toLowerCase(), { key, canonical })
+    }
+  }
+
+  const result = []
+  const seen = new Set()
+  const add = locale => {
+    const canonical = canonicalizeLocale(locale)
+    const match = canonical && canonicalKeys.get(canonical.toLowerCase())
+    if (match && !seen.has(match.key)) {
+      seen.add(match.key)
+      result.push(match)
+    }
+  }
+  const addCompatible = locale => {
+    const canonical = canonicalizeLocale(locale)
+    if (!canonical) return
+    add(canonical)
+    add(preferredChineseLocale(canonical))
+    const language = localeLanguage(canonical)
+    const match = [...canonicalKeys.values()].find(candidate => localeLanguage(candidate.canonical) === language)
+    if (match) add(match.canonical)
+  }
+
+  addCompatible(requestedLocale)
+  addCompatible(fallbackLocale)
+  addCompatible(DEFAULT_LOCALE)
+  return result
+}
+
+function selectPlural (forms, locale, values) {
+  if (!forms || typeof forms !== 'object' || Array.isArray(forms)) return null
+  const count = Number(values?.count)
+  if (!Number.isFinite(count)) return null
+
+  let category = 'other'
+  try {
+    category = new Intl.PluralRules(locale).select(count)
+  } catch {}
+  const value = forms[category] ?? forms.other
+  return typeof value === 'string' ? value : null
+}
+
+function selectTemplate (translations, requestedLocale, fallbackLocale, values) {
+  if (!translations || typeof translations !== 'object' || Array.isArray(translations)) return null
+  for (const { key, canonical } of localeCandidates(translations, requestedLocale, fallbackLocale)) {
+    const value = translations[key]
+    if (typeof value === 'string') return value
+    const plural = selectPlural(value, canonical, values)
+    if (plural !== null) return plural
+  }
+  return null
+}
+
+function interpolate (template, values) {
+  const source = String(template)
+  if (!values || typeof values !== 'object') return source
+  return source.replace(INTERPOLATION_RE, (token, name) => (
+    Object.prototype.hasOwnProperty.call(values, name)
+      ? String(values[name])
+      : token
+  ))
+}
+
+export function getT (locales, {
+  locale = getCurrentDeviceLocale(),
+  fallbackLocale = DEFAULT_LOCALE,
+  validation
+} = {}) {
+  assertLocales(locales)
+  if (validation !== undefined) validateLocales(locales, validation)
+
+  const requestedLocale = canonicalizeLocale(locale) ?? DEFAULT_LOCALE
+  const canonicalFallback = canonicalizeLocale(fallbackLocale) ?? DEFAULT_LOCALE
+
+  return function t (key, values) {
+    if (typeof key !== 'string') throw new TypeError('translation key should be a string')
+    const translations = Object.prototype.hasOwnProperty.call(locales, key) ? locales[key] : null
+    const template = selectTemplate(translations, requestedLocale, canonicalFallback, values) ?? key
+    return interpolate(template, values)
+  }
+}

package/index.js

@@ -10,6 +10,7 @@ export * as doubleDh from './double-dh/index.js'
 export * as ecdh from './ecdh/index.js'
 export * as idb from './idb/index.js'
 export * as idbQueue from './idb-queue/index.js'
+export * as i18n from './i18n/index.js'
 export * as key from './key/index.js'
 export * as network from './network/index.js'
 export * as nip19 from './nip19/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",
@@ -22,6 +22,7 @@
     "ecdh",
     "idb",
     "idb-queue",
+    "i18n",
     "index.js",
     "key",
     "network",
@@ -52,6 +53,7 @@
     "./ecdh": "./ecdh/index.js",
     "./idb": "./idb/index.js",
     "./idb-queue": "./idb-queue/index.js",
+    "./i18n": "./i18n/index.js",
     "./key": "./key/index.js",
     "./network": "./network/index.js",
     "./nip19": "./nip19/index.js",