@stacksjs/i18n 0.70.23

package/src/loader.ts

@@ -0,0 +1,333 @@
+/**
+ * Translation Loader
+ *
+ * Load translations from JSON, YAML, or TypeScript/JavaScript files.
+ */
+
+import { existsSync, readdirSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
+import { log } from '@stacksjs/logging'
+import type { TranslationMessages, Translations } from './types'
+import { addTranslations, loadTranslations } from './translator'
+
+export interface LoaderOptions {
+  /**
+   * Directory containing translation files
+   */
+  directory: string
+
+  /**
+   * File extensions to load
+   * @default ['.json', '.yaml', '.yml', '.ts', '.js']
+   */
+  extensions?: string[]
+
+  /**
+   * Whether to load files recursively
+   * @default false
+   */
+  recursive?: boolean
+
+  /**
+   * Namespace separator for nested directories
+   * @default '.'
+   */
+  namespaceSeparator?: string
+}
+
+/**
+ * Load translations from a directory
+ */
+export async function loadFromDirectory(options: LoaderOptions): Promise<Translations> {
+  const {
+    directory,
+    extensions = ['.json', '.yaml', '.yml', '.ts', '.js'],
+    recursive = false,
+    namespaceSeparator = '.',
+  } = options
+
+  const translations: Translations = {}
+
+  if (!existsSync(directory)) {
+    log.warn(`[i18n] Translation directory not found: ${directory}`)
+    return translations
+  }
+
+  await loadDirectory(directory, translations, extensions, recursive, namespaceSeparator, '')
+
+  // Also register with global i18n
+  loadTranslations(translations)
+
+  return translations
+}
+
+/**
+ * Recursively load a directory
+ */
+async function loadDirectory(
+  dir: string,
+  translations: Translations,
+  extensions: string[],
+  recursive: boolean,
+  namespaceSeparator: string,
+  namespace: string,
+): Promise<void> {
+  const entries = readdirSync(dir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name)
+
+    if (entry.isDirectory()) {
+      // Check if this is a locale directory (e.g., "en", "fr", "de")
+      const locale = entry.name
+
+      // If it looks like a locale code, load all files in it as that locale
+      if (isLocaleCode(locale)) {
+        await loadLocaleDirectory(fullPath, locale, translations, extensions)
+      }
+      else if (recursive) {
+        // Otherwise, treat as namespace
+        const newNamespace = namespace
+          ? `${namespace}${namespaceSeparator}${entry.name}`
+          : entry.name
+
+        await loadDirectory(
+          fullPath,
+          translations,
+          extensions,
+          recursive,
+          namespaceSeparator,
+          newNamespace,
+        )
+      }
+    }
+    else if (entry.isFile()) {
+      const ext = extname(entry.name)
+
+      if (extensions.includes(ext)) {
+        // File name (without extension) is the locale
+        const locale = basename(entry.name, ext)
+
+        if (!translations[locale]) {
+          translations[locale] = {}
+        }
+
+        const messages = await loadFile(fullPath)
+
+        if (namespace) {
+          // Nest under namespace
+          setNested(translations[locale], namespace, messages, namespaceSeparator)
+        }
+        else {
+          // Merge at root
+          translations[locale] = deepMerge(translations[locale], messages)
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Load all translation files in a locale directory
+ */
+async function loadLocaleDirectory(
+  dir: string,
+  locale: string,
+  translations: Translations,
+  extensions: string[],
+): Promise<void> {
+  if (!translations[locale]) {
+    translations[locale] = {}
+  }
+
+  const entries = readdirSync(dir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+
+    const ext = extname(entry.name)
+    if (!extensions.includes(ext)) continue
+
+    const fullPath = join(dir, entry.name)
+    const namespace = basename(entry.name, ext)
+
+    const messages = await loadFile(fullPath)
+
+    // If the file is named after the locale (e.g., "en.json" in "en" folder), merge at root
+    if (namespace === locale) {
+      translations[locale] = deepMerge(translations[locale], messages)
+    }
+    else {
+      // Otherwise, use filename as namespace
+      translations[locale][namespace] = messages
+    }
+  }
+}
+
+/**
+ * Load a single translation file
+ */
+export async function loadFile(filePath: string): Promise<TranslationMessages> {
+  const ext = extname(filePath).toLowerCase()
+  const content = await readFile(filePath, 'utf8')
+
+  switch (ext) {
+    case '.json':
+      try {
+        return JSON.parse(content) as TranslationMessages
+      }
+      catch {
+        throw new Error(`Invalid JSON in translation file: ${filePath}`)
+      }
+
+    case '.yaml':
+    case '.yml':
+      return parseYaml(content)
+
+    case '.ts':
+    case '.js': {
+      // Dynamic import for JS/TS files
+      const module = await import(filePath)
+      return module.default || module
+    }
+
+    default:
+      throw new Error(`Unsupported file type: ${ext}`)
+  }
+}
+
+/**
+ * Load a single locale from a file or directory
+ */
+export async function loadLocale(
+  locale: string,
+  path: string,
+): Promise<TranslationMessages> {
+  const messages = await loadFile(path)
+  addTranslations(locale, messages)
+  return messages
+}
+
+/**
+ * Parse YAML translation files.
+ */
+function parseYaml(content: string): TranslationMessages {
+  try {
+    const parsed = Bun.YAML.parse(content)
+
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('YAML content must be an object at the root level')
+    }
+
+    return parsed as TranslationMessages
+  }
+  catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown YAML parse error'
+    throw new Error(`Invalid YAML translation file: ${message}`)
+  }
+}
+
+/**
+ * Check if a string looks like a locale code
+ */
+function isLocaleCode(str: string): boolean {
+  // Match patterns like "en", "en-US", "zh-Hans", etc.
+  return /^[a-z]{2}(-[A-Z]{2})?(-[A-Za-z]+)?$/i.test(str)
+}
+
+/**
+ * Set a nested value in an object
+ */
+function setNested(
+  obj: TranslationMessages,
+  path: string,
+  value: TranslationMessages,
+  separator: string,
+): void {
+  const parts = path.split(separator)
+  let current = obj
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i]
+    if (!current[part] || typeof current[part] === 'string') {
+      current[part] = {}
+    }
+    current = current[part] as TranslationMessages
+  }
+
+  const lastPart = parts[parts.length - 1]
+  current[lastPart] = value
+}
+
+/**
+ * Deep merge two objects
+ */
+function deepMerge(target: TranslationMessages, source: TranslationMessages): TranslationMessages {
+  const result = { ...target }
+
+  for (const key of Object.keys(source)) {
+    const sourceValue = source[key]
+    const targetValue = result[key]
+
+    if (
+      typeof sourceValue === 'object'
+      && sourceValue !== null
+      && typeof targetValue === 'object'
+      && targetValue !== null
+    ) {
+      result[key] = deepMerge(
+        targetValue as TranslationMessages,
+        sourceValue as TranslationMessages,
+      )
+    }
+    else {
+      result[key] = sourceValue
+    }
+  }
+
+  return result
+}
+
+/**
+ * Create a translation loader for a specific directory
+ */
+export function createLoader(directory: string, options: Partial<Omit<LoaderOptions, 'directory'>> = {}) {
+  return {
+    load: () => loadFromDirectory({ directory, ...options }),
+    loadLocale: (locale: string, filename: string) => loadLocale(locale, join(directory, filename)),
+  }
+}
+
+/**
+ * Load translations via `@stacksjs/ts-i18n` and register them with the
+ * global translator. This is the recommended path for new projects —
+ * it gets you:
+ *
+ *   - Per-locale subdirectory namespacing (en/auth.yaml → en.auth.*)
+ *   - First-class .ts/.json/.yaml support with consistent error
+ *     messages
+ *   - Optional `.d.ts` codegen via `generateI18nTypes()` so message
+ *     keys autocomplete in `t('…')` calls
+ *
+ * The legacy `loadFromDirectory()` remains for projects that depend
+ * on its specific behavior; new code should prefer this entry.
+ *
+ * @example
+ * ```ts
+ * await loadFromTsI18n({
+ *   translationsDir: path.userI18nPath(),
+ *   defaultLocale: 'en',
+ *   fallbackLocale: 'en',
+ *   sources: ['yaml', 'ts', 'json'],
+ *   optional: true,
+ * })
+ * ```
+ */
+export async function loadFromTsI18n(config: import('@stacksjs/ts-i18n').I18nConfig): Promise<Translations> {
+  const { loadTranslations: tsLoad } = await import('@stacksjs/ts-i18n')
+  const localeMap = await tsLoad(config) as Record<string, TranslationMessages>
+  // Register each locale with the Stacks translator so `t()` picks it up.
+  loadTranslations(localeMap as unknown as Translations)
+  return localeMap as unknown as Translations
+}

package/src/pluralization.ts

@@ -0,0 +1,287 @@
+/**
+ * Pluralization Rules
+ *
+ * Implements CLDR plural rules for various languages.
+ * @see https://cldr.unicode.org/index/cldr-spec/plural-rules
+ */
+
+export type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other'
+
+export type PluralRule = (_n: number) => PluralCategory
+
+/**
+ * Get the plural category for a number in a given locale
+ */
+export function getPluralCategory(n: number, locale: string): PluralCategory {
+  const rule = getPluralRule(locale)
+  return rule(n)
+}
+
+/**
+ * Get the plural rule function for a locale
+ */
+export function getPluralRule(locale: string): PluralRule {
+  // Get base language code
+  const lang = locale.split('-')[0].toLowerCase()
+
+  const rule = pluralRules[lang]
+  if (rule) return rule
+
+  // Default to 'other' for unknown locales
+  return () => 'other'
+}
+
+/**
+ * Parse a plural string into its forms
+ *
+ * Supports formats:
+ * - "one | other" (simple)
+ * - "zero | one | other" (with zero)
+ * - "{0} item | {0} items" (with placeholders)
+ * - "no items | one item | {n} items" (with special forms)
+ */
+export function parsePluralForms(
+  str: string,
+  separator = '|',
+): Map<PluralCategory, string> {
+  const parts = str.split(separator).map(s => s.trim())
+  const forms = new Map<PluralCategory, string>()
+
+  if (parts.length === 1) {
+    forms.set('other', parts[0])
+  }
+  else if (parts.length === 2) {
+    forms.set('one', parts[0])
+    forms.set('other', parts[1])
+  }
+  else if (parts.length === 3) {
+    forms.set('zero', parts[0])
+    forms.set('one', parts[1])
+    forms.set('other', parts[2])
+  }
+  else if (parts.length >= 4) {
+    // Extended format: zero | one | two | few | many | other
+    const categories: PluralCategory[] = ['zero', 'one', 'two', 'few', 'many', 'other']
+    for (let i = 0; i < parts.length && i < categories.length; i++) {
+      forms.set(categories[i], parts[i])
+    }
+  }
+
+  return forms
+}
+
+/**
+ * Select the appropriate plural form for a count
+ */
+export function selectPluralForm(
+  forms: Map<PluralCategory, string>,
+  count: number,
+  locale: string,
+): string {
+  const category = getPluralCategory(count, locale)
+
+  // Try exact category first
+  if (forms.has(category)) {
+    return forms.get(category)!
+  }
+
+  // Fall back to 'other'
+  if (forms.has('other')) {
+    return forms.get('other')!
+  }
+
+  // Last resort: return first available form
+  const first = forms.values().next()
+  return first.done ? '' : first.value
+}
+
+/**
+ * Plural rules for various languages
+ * Based on CLDR plural rules
+ */
+const pluralRules: Record<string, PluralRule> = {
+  // === One/Other languages ===
+
+  // English, German, Dutch, etc.
+  en: n => (n === 1 ? 'one' : 'other'),
+  de: n => (n === 1 ? 'one' : 'other'),
+  nl: n => (n === 1 ? 'one' : 'other'),
+  es: n => (n === 1 ? 'one' : 'other'),
+  it: n => (n === 1 ? 'one' : 'other'),
+  pt: n => (n === 1 ? 'one' : 'other'),
+  sv: n => (n === 1 ? 'one' : 'other'),
+  da: n => (n === 1 ? 'one' : 'other'),
+  no: n => (n === 1 ? 'one' : 'other'),
+  fi: n => (n === 1 ? 'one' : 'other'),
+  el: n => (n === 1 ? 'one' : 'other'),
+  he: n => (n === 1 ? 'one' : 'other'),
+  hu: n => (n === 1 ? 'one' : 'other'),
+  tr: n => (n === 1 ? 'one' : 'other'),
+
+  // === No plural (always other) ===
+
+  // Chinese, Japanese, Korean, Vietnamese, Thai
+  zh: () => 'other',
+  ja: () => 'other',
+  ko: () => 'other',
+  vi: () => 'other',
+  th: () => 'other',
+  id: () => 'other',
+  ms: () => 'other',
+
+  // === French (0-1 is one) ===
+
+  fr: n => (n === 0 || n === 1 ? 'one' : 'other'),
+
+  // === Russian, Ukrainian (complex) ===
+
+  ru: (n) => {
+    const mod10 = n % 10
+    const mod100 = n % 100
+
+    if (mod10 === 1 && mod100 !== 11) return 'one'
+    if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)) return 'few'
+    if (mod10 === 0 || (mod10 >= 5 && mod10 <= 9) || (mod100 >= 11 && mod100 <= 14)) return 'many'
+    return 'other'
+  },
+
+  uk: (n) => {
+    const mod10 = n % 10
+    const mod100 = n % 100
+
+    if (mod10 === 1 && mod100 !== 11) return 'one'
+    if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)) return 'few'
+    if (mod10 === 0 || (mod10 >= 5 && mod10 <= 9) || (mod100 >= 11 && mod100 <= 14)) return 'many'
+    return 'other'
+  },
+
+  // === Polish (complex) ===
+
+  pl: (n) => {
+    const mod10 = n % 10
+    const mod100 = n % 100
+
+    if (n === 1) return 'one'
+    if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)) return 'few'
+    if (mod10 === 0 || mod10 === 1 || (mod10 >= 5 && mod10 <= 9) || (mod100 >= 12 && mod100 <= 14)) return 'many'
+    return 'other'
+  },
+
+  // === Czech, Slovak ===
+
+  cs: (n) => {
+    if (n === 1) return 'one'
+    if (n >= 2 && n <= 4) return 'few'
+    return 'other'
+  },
+
+  sk: (n) => {
+    if (n === 1) return 'one'
+    if (n >= 2 && n <= 4) return 'few'
+    return 'other'
+  },
+
+  // === Arabic (complex with dual) ===
+
+  ar: (n) => {
+    if (n === 0) return 'zero'
+    if (n === 1) return 'one'
+    if (n === 2) return 'two'
+
+    const mod100 = n % 100
+    if (mod100 >= 3 && mod100 <= 10) return 'few'
+    if (mod100 >= 11 && mod100 <= 99) return 'many'
+    return 'other'
+  },
+
+  // === Welsh (with zero, one, two, few, many) ===
+
+  cy: (n) => {
+    if (n === 0) return 'zero'
+    if (n === 1) return 'one'
+    if (n === 2) return 'two'
+    if (n === 3) return 'few'
+    if (n === 6) return 'many'
+    return 'other'
+  },
+
+  // === Slovenian (with dual) ===
+
+  sl: (n) => {
+    const mod100 = n % 100
+
+    if (mod100 === 1) return 'one'
+    if (mod100 === 2) return 'two'
+    if (mod100 === 3 || mod100 === 4) return 'few'
+    return 'other'
+  },
+
+  // === Irish ===
+
+  ga: (n) => {
+    if (n === 1) return 'one'
+    if (n === 2) return 'two'
+    if (n >= 3 && n <= 6) return 'few'
+    if (n >= 7 && n <= 10) return 'many'
+    return 'other'
+  },
+
+  // === Lithuanian ===
+
+  lt: (n) => {
+    const mod10 = n % 10
+    const mod100 = n % 100
+
+    if (mod10 === 1 && (mod100 < 11 || mod100 > 19)) return 'one'
+    if (mod10 >= 2 && mod10 <= 9 && (mod100 < 11 || mod100 > 19)) return 'few'
+    return 'other'
+  },
+
+  // === Latvian ===
+
+  lv: (n) => {
+    const mod10 = n % 10
+    const mod100 = n % 100
+
+    if (n === 0) return 'zero'
+    if (mod10 === 1 && mod100 !== 11) return 'one'
+    return 'other'
+  },
+
+  // === Romanian ===
+
+  ro: (n) => {
+    if (n === 1) return 'one'
+
+    const mod100 = n % 100
+    if (n === 0 || (mod100 >= 1 && mod100 <= 19)) return 'few'
+    return 'other'
+  },
+
+  // === Hindi ===
+
+  hi: n => (n === 0 || n === 1 ? 'one' : 'other'),
+}
+
+/**
+ * Get all supported locales for pluralization
+ */
+export function getSupportedPluralLocales(): string[] {
+  return Object.keys(pluralRules)
+}
+
+/**
+ * Check if a locale has custom plural rules
+ */
+export function hasPluralRule(locale: string): boolean {
+  const lang = locale.split('-')[0].toLowerCase()
+  return lang in pluralRules
+}
+
+/**
+ * Add a custom plural rule for a locale
+ */
+export function addPluralRule(locale: string, rule: PluralRule): void {
+  const lang = locale.split('-')[0].toLowerCase()
+  pluralRules[lang] = rule
+}