@gravito/cosmos 3.0.1 → 3.1.0

package/src/index.ts

@@ -1,19 +1,32 @@
+/**
+ * @file packages/cosmos/src/index.ts
+ * @module @gravito/cosmos
+ * @description Entry point for the Gravito Cosmos internationalization module.
+ */
+
 import type { GravitoMiddleware, GravitoOrbit, PlanetCore } from '@gravito/core'
 import { type I18nConfig, I18nManager, type I18nService, localeMiddleware } from './I18nService'
 
 declare module '@gravito/core' {
   interface GravitoVariables {
-    /** I18n service for translations */
+    /**
+     * The request-scoped I18n service instance.
+     * Provides translation and locale management for the current request.
+     */
     i18n: I18nService
   }
 }
 
 /**
- * OrbitCosmos provides internationalization (i18n) support for Gravito.
- * It manages translations, locale switching, and provides a middleware for request-scoped locale detection.
+ * OrbitCosmos provides internationalization (i18n) support for the Gravito framework.
+ *
+ * It manages global translation resources, handles locale detection through middleware,
+ * and provides request-scoped i18n instances.
  *
  * @example
  * ```typescript
+ * import { OrbitCosmos } from '@gravito/cosmos'
+ *
  * const cosmos = new OrbitCosmos({
  *   defaultLocale: 'en',
  *   supportedLocales: ['en', 'zh-TW'],
@@ -25,19 +38,25 @@ declare module '@gravito/core' {
  * core.addOrbit(cosmos);
  * ```
  * @public
+ * @since 3.0.0
  */
 export class OrbitCosmos implements GravitoOrbit {
   /**
    * Create a new OrbitCosmos instance.
-   * @param config - The i18n configuration options.
+   *
+   * @param config - The i18n configuration options including locales and translations.
    */
   constructor(private config: I18nConfig) {}
 
   /**
    * Install the i18n service into PlanetCore.
-   * Registers the I18nManager and sets up the locale middleware.
    *
-   * @param core - The PlanetCore instance.
+   * This method:
+   * 1. Initializes the central `I18nManager`.
+   * 2. Registers the manager in the IoC container as 'i18n'.
+   * 3. Injects the `localeMiddleware` into the adapter for all routes.
+   *
+   * @param core - The PlanetCore instance to install into.
    */
   install(core: PlanetCore): void {
     const i18nManager = new I18nManager(this.config)

package/src/loader.ts

@@ -1,15 +1,28 @@
+/**
+ * @file packages/cosmos/src/loader.ts
+ * @module @gravito/cosmos/loader
+ * @description Utilities for loading translation files from the filesystem.
+ */
+
 import { readdir, readFile } from 'node:fs/promises'
 import { join, parse } from 'node:path'
 
 /**
- * Load translations from a directory
- * Structure:
+ * Load translations from a directory.
+ *
+ * Scans the specified directory for JSON files and loads them as translation bundles.
+ * The filename (without extension) is used as the locale key.
+ *
+ * @example
+ * ```
  * /lang
- *   /en.json -> { "welcome": "Hello" }
- *   /zh.json -> { "welcome": "Hello" }
- *   /en/auth.json -> { "failed": "Login failed" } (Optional deep structure, maybe later)
+ *   /en.json    -> { "welcome": "Hello" }
+ *   /zh-TW.json -> { "welcome": "你好" }
+ * ```
  *
- * For now, we support flat JSON files per locale: en.json, zh.json
+ * @param directory - The absolute path to the translations directory.
+ * @returns A promise that resolves to a map of locale -> translations.
+ * @public
  */
 export async function loadTranslations(
   directory: string
@@ -25,12 +38,9 @@ export async function loadTranslations(
       }
 
       const locale = parse(file).name // 'en' from 'en.json'
-      const content = await readFile(join(directory, file), 'utf-8')
-
-      try {
-        translations[locale] = JSON.parse(content)
-      } catch (e) {
-        console.error(`[Orbit-I18n] Failed to parse translation file: ${file}`, e)
+      const translationsForLocale = await loadLocale(directory, locale)
+      if (translationsForLocale) {
+        translations[locale] = translationsForLocale
       }
     }
   } catch (_e) {
@@ -41,3 +51,26 @@ export async function loadTranslations(
 
   return translations
 }
+
+/**
+ * Load translations for a specific locale from a directory.
+ *
+ * Expects a file named `{locale}.json` in the given directory.
+ *
+ * @param directory - The directory containing translation files.
+ * @param locale - The locale string to load.
+ * @returns A promise that resolves to the translations map, or null if the file could not be read.
+ * @public
+ */
+export async function loadLocale(
+  directory: string,
+  locale: string
+): Promise<Record<string, string> | null> {
+  const filePath = join(directory, `${locale}.json`)
+  try {
+    const content = await readFile(filePath, 'utf-8')
+    return JSON.parse(content)
+  } catch {
+    return null
+  }
+}

package/tests/helpers/factory.ts

@@ -0,0 +1,41 @@
+import { type I18nConfig, I18nManager, type TranslationMap } from '../../src/I18nService'
+
+export function createTestManager(overrides?: Partial<I18nConfig>): I18nManager {
+  return new I18nManager({
+    defaultLocale: 'en',
+    supportedLocales: ['en', 'zh-TW'],
+    translations: {
+      en: {
+        common: {
+          welcome: 'Welcome',
+          goodbye: 'Goodbye',
+        },
+      },
+      'zh-TW': {
+        common: {
+          welcome: '歡迎',
+          goodbye: '再見',
+        },
+      },
+    },
+    ...overrides,
+  })
+}
+
+export function generateLargeTranslations(
+  locales = 5,
+  keys = 1000
+): Record<string, TranslationMap> {
+  const result: Record<string, TranslationMap> = {}
+
+  for (let l = 0; l < locales; l++) {
+    const locale = `locale${l}`
+    result[locale] = {}
+
+    for (let k = 0; k < keys; k++) {
+      result[locale][`key${k}`] = `Translation ${k} for ${locale}`
+    }
+  }
+
+  return result
+}

package/tests/performance/translate.bench.ts

@@ -0,0 +1,27 @@
+import { bench, run } from 'mitata'
+import { I18nManager } from '../../src/I18nService'
+import { generateLargeTranslations } from '../helpers/factory'
+
+const manager = new I18nManager({
+  defaultLocale: 'en',
+  supportedLocales: ['en', 'zh-TW'],
+  translations: generateLargeTranslations(),
+})
+
+// Warmup
+manager.translate('locale0', 'key0')
+
+bench('Simple translation (cache hit)', () => {
+  manager.translate('locale0', 'key0')
+})
+
+bench('Batch translation (100 keys)', () => {
+  const keys = Array.from({ length: 100 }, (_, i) => `key${i}`)
+  manager.tMany(keys)
+})
+
+bench('Fallback chain (missing key)', () => {
+  manager.translate('locale0', 'missing.key')
+})
+
+await run()

package/tests/unit/api.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'bun:test'
+import { I18nManager } from '../../src/I18nService'
+
+describe('I18nManager API', () => {
+  it('supports multiple translations', () => {
+    const manager = new I18nManager({
+      defaultLocale: 'en',
+      supportedLocales: ['en'],
+      translations: {
+        en: {
+          hello: 'Hello',
+          goodbye: 'Goodbye',
+        },
+      },
+    })
+
+    const translations = manager.tMany(['hello', 'goodbye', 'missing'])
+
+    expect(translations.hello).toBe('Hello')
+    expect(translations.goodbye).toBe('Goodbye')
+    expect(translations.missing).toBe('missing')
+  })
+
+  it('reports loaded locales', async () => {
+    const manager = new I18nManager({
+      defaultLocale: 'en',
+      supportedLocales: ['en', 'fr'],
+      translations: {
+        en: { hello: 'Hello' },
+      },
+    })
+
+    expect(manager.getLocales()).toContain('en')
+    expect(manager.isLocaleLoaded('en')).toBe(true)
+    expect(manager.isLocaleLoaded('fr')).toBe(false)
+  })
+})

package/tests/unit/detector.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it, jest } from 'bun:test'
+import {
+  DefaultDetectors,
+  type I18nService,
+  type LocaleDetector,
+  localeMiddleware,
+} from '../../src/I18nService'
+
+describe('Locale Detectors', () => {
+  const mockContext = (params: any = {}) => ({
+    req: {
+      param: (key: string) => params.param?.[key],
+      query: (key: string) => params.query?.[key],
+      header: (key: string) => params.header?.[key],
+    },
+    set: jest.fn(),
+  })
+
+  it('detects from route param', async () => {
+    const ctx = mockContext({ param: { locale: 'fr' } })
+    const detector = DefaultDetectors.find((d) => d.name === 'routeParam')!
+    expect(await detector.detect(ctx)).toBe('fr')
+  })
+
+  it('detects from query', async () => {
+    const ctx = mockContext({ query: { lang: 'de' } })
+    const detector = DefaultDetectors.find((d) => d.name === 'query')!
+    expect(await detector.detect(ctx)).toBe('de')
+  })
+
+  it('detects from header', async () => {
+    const ctx = mockContext({ header: { 'Accept-Language': 'es-ES,es;q=0.9' } })
+    const detector = DefaultDetectors.find((d) => d.name === 'header')!
+    expect(await detector.detect(ctx)).toBe('es-ES')
+  })
+})
+
+describe('Locale Middleware', () => {
+  it('uses detectors in order', async () => {
+    const mockManager = {
+      ensureLocale: jest.fn(),
+      clone: jest.fn().mockReturnValue({}),
+    } as unknown as I18nService
+
+    const middleware = localeMiddleware(mockManager, DefaultDetectors)
+
+    const ctx1 = {
+      req: {
+        param: () => 'fr',
+        query: () => 'de',
+        header: () => 'es',
+      },
+      set: jest.fn(),
+    }
+    await middleware(ctx1 as any, async () => {})
+    expect(mockManager.ensureLocale).toHaveBeenCalledWith('fr')
+    expect(mockManager.clone).toHaveBeenCalledWith('fr')
+
+    const ctx2 = {
+      req: {
+        param: () => undefined,
+        query: () => 'de',
+        header: () => 'es',
+      },
+      set: jest.fn(),
+    }
+    await middleware(ctx2 as any, async () => {})
+    expect(mockManager.ensureLocale).toHaveBeenCalledWith('de')
+  })
+})

package/tests/unit/edge.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'bun:test'
+import { I18nManager } from '../../src/I18nService'
+
+describe('I18nManager - Edge Cases', () => {
+  describe('Empty Translations', () => {
+    it('should handle empty translation object', () => {
+      const manager = new I18nManager({
+        defaultLocale: 'en',
+        supportedLocales: ['en'],
+        translations: {},
+      })
+      expect(manager.translate('en', 'any.key')).toBe('any.key')
+    })
+
+    it('should handle empty string translation', () => {
+      const manager = new I18nManager({
+        defaultLocale: 'en',
+        supportedLocales: ['en'],
+        translations: { en: { empty: '' } },
+      })
+      expect(manager.translate('en', 'empty')).toBe('')
+    })
+  })
+
+  describe('Special Characters', () => {
+    it('should handle keys with special characters', () => {
+      const manager = new I18nManager({
+        defaultLocale: 'en',
+        supportedLocales: ['en'],
+        translations: { en: { 'key.with.dots': 'value' } },
+      })
+      expect(manager.translate('en', 'key.with.dots')).toBe('key.with.dots')
+    })
+
+    it('should handle unicode keys', () => {
+      const manager = new I18nManager({
+        defaultLocale: 'zh-TW',
+        supportedLocales: ['zh-TW'],
+        translations: { 'zh-TW': { 歡迎: '歡迎訊息' } },
+      })
+      expect(manager.translate('zh-TW', '歡迎')).toBe('歡迎訊息')
+    })
+
+    it('should handle HTML in translations', () => {
+      const manager = new I18nManager({
+        defaultLocale: 'en',
+        supportedLocales: ['en'],
+        translations: { en: { html: '<strong>Bold</strong>' } },
+      })
+      expect(manager.translate('en', 'html')).toBe('<strong>Bold</strong>')
+    })
+  })
+
+  describe('Deep Nesting', () => {
+    it('should handle deeply nested keys (10 levels)', () => {
+      const translations = {
+        en: {
+          l1: { l2: { l3: { l4: { l5: { l6: { l7: { l8: { l9: { l10: 'deep' } } } } } } } } },
+        },
+      }
+      const manager = new I18nManager({
+        defaultLocale: 'en',
+        supportedLocales: ['en'],
+        translations,
+      })
+      expect(manager.translate('en', 'l1.l2.l3.l4.l5.l6.l7.l8.l9.l10')).toBe('deep')
+    })
+  })
+
+  describe('Parameter Replacement', () => {
+    it('should handle missing parameters', () => {
+      const manager = new I18nManager({
+        defaultLocale: 'en',
+        supportedLocales: ['en'],
+        translations: { en: { greeting: 'Hello :name!' } },
+      })
+      expect(manager.translate('en', 'greeting', {})).toBe('Hello :name!')
+    })
+
+    it('should handle extra parameters', () => {
+      const manager = new I18nManager({
+        defaultLocale: 'en',
+        supportedLocales: ['en'],
+        translations: { en: { greeting: 'Hello :name!' } },
+      })
+      expect(manager.translate('en', 'greeting', { name: 'Carl', extra: 'ignored' })).toBe(
+        'Hello Carl!'
+      )
+    })
+
+    it('should handle parameter with special regex characters', () => {
+      const manager = new I18nManager({
+        defaultLocale: 'en',
+        supportedLocales: ['en'],
+        translations: { en: { msg: 'Value: :value' } },
+      })
+      expect(manager.translate('en', 'msg', { value: '$100.00' })).toBe('Value: $100.00')
+    })
+  })
+})

package/tests/unit/fallback.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'bun:test'
+import { I18nManager } from '../../src/I18nService'
+
+describe('Fallback Strategies', () => {
+  it('uses default fallback chain (defaultLocale)', () => {
+    const manager = new I18nManager({
+      defaultLocale: 'en',
+      supportedLocales: ['en', 'fr'],
+      translations: {
+        en: { hello: 'Hello' },
+        fr: {},
+      },
+    })
+    expect(manager.translate('fr', 'hello')).toBe('Hello')
+  })
+
+  it('uses configured fallback chain', () => {
+    const manager = new I18nManager({
+      defaultLocale: 'en',
+      supportedLocales: ['en', 'es', 'pt'],
+      translations: {
+        en: { hello: 'Hello' },
+        es: { hello: 'Hola' },
+        pt: {},
+      },
+      fallback: {
+        fallbackChain: {
+          pt: ['es', 'en'],
+        },
+      },
+    })
+    expect(manager.translate('pt', 'hello')).toBe('Hola')
+  })
+
+  it('handles missing key strategies', () => {
+    const manager = new I18nManager({
+      defaultLocale: 'en',
+      supportedLocales: ['en'],
+      translations: { en: {} },
+      fallback: {
+        onMissingKey: 'empty',
+      },
+    })
+    expect(manager.translate('en', 'missing')).toBe('')
+
+    const managerThrow = new I18nManager({
+      defaultLocale: 'en',
+      supportedLocales: ['en'],
+      translations: { en: {} },
+      fallback: {
+        onMissingKey: 'throw',
+      },
+    })
+    expect(() => managerThrow.translate('en', 'missing')).toThrow()
+
+    const managerCustom = new I18nManager({
+      defaultLocale: 'en',
+      supportedLocales: ['en'],
+      translations: { en: {} },
+      fallback: {
+        onMissingKey: (key, locale) => `Missing ${key} in ${locale}`,
+      },
+    })
+    expect(managerCustom.translate('en', 'missing')).toBe('Missing missing in en')
+  })
+})

package/tests/unit/lazy.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'bun:test'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { I18nManager } from '../../src/I18nService'
+
+describe('Lazy Loading', () => {
+  it('loads translations on demand', async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'gravito-i18n-lazy-'))
+
+    try {
+      writeFileSync(join(tmpDir, 'fr.json'), JSON.stringify({ greeting: 'Bonjour' }))
+
+      const manager = new I18nManager({
+        defaultLocale: 'en',
+        supportedLocales: ['en', 'fr'],
+        lazyLoad: {
+          baseDir: tmpDir,
+        },
+      })
+
+      expect(manager.translate('fr', 'greeting')).toBe('greeting')
+
+      await manager.ensureLocale('fr')
+
+      expect(manager.translate('fr', 'greeting')).toBe('Bonjour')
+
+      await manager.ensureLocale('fr')
+      expect(manager.translate('fr', 'greeting')).toBe('Bonjour')
+    } finally {
+      await rm(tmpDir, { force: true, recursive: true })
+    }
+  })
+})

package/tests/{loader.test.ts → unit/loader.test.ts}

@@ -3,7 +3,7 @@ import { mkdtempSync, writeFileSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { loadTranslations } from '../src/loader'
+import { loadTranslations } from '../../src/loader'
 
 describe('loadTranslations', () => {
   it('loads json translation files from a directory', async () => {

package/tests/{manager.test.ts → unit/manager.test.ts}

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test'
-import { I18nManager } from '../src/index'
+import { I18nManager } from '../../src/index'
 
 describe('Orbit I18n Manager', () => {
   const _config = {

package/tests/unit/plural.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'bun:test'
+import { I18nManager } from '../../src/I18nService'
+
+describe('Pluralization', () => {
+  it('handles plural forms correctly', () => {
+    const translations = {
+      en: {
+        items: {
+          zero: 'No items',
+          one: '1 item',
+          other: ':count items',
+        },
+        apples: {
+          one: 'an apple',
+          other: ':count apples',
+        },
+      },
+      fr: {
+        // French treats 0 and 1 as singular (usually)
+        items: {
+          one: 'un élément', // used for 0 and 1 in standard FR rule? Wait.
+          other: ':count éléments',
+        },
+      },
+    }
+
+    const manager = new I18nManager({
+      defaultLocale: 'en',
+      supportedLocales: ['en', 'fr'],
+      translations,
+    })
+
+    // English
+    expect(manager.translate('en', 'items', { count: 0 })).toBe('No items') // explicit zero
+    expect(manager.translate('en', 'items', { count: 1 })).toBe('1 item')
+    expect(manager.translate('en', 'items', { count: 2 })).toBe('2 items')
+    expect(manager.translate('en', 'items', { count: 10 })).toBe('10 items')
+
+    // Missing zero key uses 'other' or 'one' based on rules?
+    // English rules: one (n=1), other (n!=1). 0 falls to other.
+    expect(manager.translate('en', 'apples', { count: 0 })).toBe('0 apples')
+    expect(manager.translate('en', 'apples', { count: 1 })).toBe('an apple')
+
+    // French
+    // French rules: one (n>=0 && n<2), other (everything else)
+    // So 0 is one. 1 is one. 2 is other.
+    // Wait, let's verify node/bun Intl behavior.
+
+    // In our code, we check 'zero' key FIRST if count === 0.
+    // But 'fr' translations above don't have 'zero' key.
+    // So it should fall to `pluralMap[form]`.
+    // For fr, 0 -> 'one'.
+
+    expect(manager.translate('fr', 'items', { count: 0 })).toBe('un élément')
+    expect(manager.translate('fr', 'items', { count: 1 })).toBe('un élément')
+    expect(manager.translate('fr', 'items', { count: 2 })).toBe('2 éléments')
+  })
+})

package/tests/{service.test.ts → unit/service.test.ts}

@@ -1,6 +1,6 @@
 import { describe, expect, it, jest } from 'bun:test'
-import { I18nInstance, I18nManager, localeMiddleware } from '../src/I18nService'
-import { I18nOrbit, OrbitCosmos } from '../src/index'
+import { I18nInstance, I18nManager, localeMiddleware } from '../../src/I18nService'
+import { I18nOrbit, OrbitCosmos } from '../../src/index'
 
 describe('I18nManager and I18nInstance', () => {
   const baseConfig = {

package/tsconfig.json

@@ -1,26 +1,14 @@
 {
-    "extends": "../../tsconfig.json",
-    "compilerOptions": {
-        "outDir": "./dist",
-        "baseUrl": ".",
-        "paths": {
-            "@gravito/core": [
-                "../../packages/core/src/index.ts"
-            ],
-            "@gravito/*": [
-                "../../packages/*/src/index.ts"
-            ]
-        },
-        "types": [
-            "bun-types"
-        ]
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "baseUrl": ".",
+    "paths": {
+      "@gravito/core": ["../../packages/core/src/index.ts"],
+      "@gravito/*": ["../../packages/*/src/index.ts"]
     },
-    "include": [
-        "src/**/*"
-    ],
-    "exclude": [
-        "node_modules",
-        "dist",
-        "**/*.test.ts"
-    ]
-}
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/.turbo/turbo-build.log

@@ -1,20 +0,0 @@
-
-$ bun run build.ts
-Building @gravito/cosmos...
-⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Target: esnext
-ESM Build start
-CJS Build start
-ESM You have emitDecoratorMetadata enabled but @swc/core was not installed, skipping swc plugin
-CJS You have emitDecoratorMetadata enabled but @swc/core was not installed, skipping swc plugin
-ESM dist/index.js 6.93 KB
-ESM ⚡️ Build success in 72ms
-CJS dist/index.cjs 8.20 KB
-CJS ⚡️ Build success in 72ms
-DTS Build start
-DTS ⚡️ Build success in 7986ms
-DTS dist/index.d.ts  7.87 KB
-DTS dist/index.d.cts 7.87 KB
-⠙✅ Build complete!