@gravito/cosmos 3.0.1 → 3.2.0

package/MIGRATION.md

@@ -0,0 +1,331 @@
+# Migration Guide: Cosmos v1.x → v2.0
+
+## Overview
+
+Cosmos v2.0 introduces Edge Runtime support while maintaining full backward compatibility with v1.x. This guide helps you migrate to v2.0 and leverage new features.
+
+## Breaking Changes
+
+**None!** v2.0 is fully backward compatible with v1.x.
+
+All existing code will continue to work without modifications.
+
+## What's New in v2.0
+
+### Edge Runtime Support
+
+Cosmos now runs in Edge Runtime environments:
+- ✅ Cloudflare Workers
+- ✅ Vercel Edge Functions
+- ✅ Deno Deploy
+- ✅ Node.js (existing support)
+
+### New Loaders
+
+- **MemoryLoader**: Static translations for Edge environments
+- **EdgeKVLoader**: Generic KV storage abstraction
+- **CloudflareKVLoader**: Cloudflare Workers KV
+- **VercelKVLoader**: Vercel KV
+
+### Runtime Detection
+
+- `detectRuntime()`: Auto-detect execution environment
+- `isNode()`, `isEdge()`: Helper functions
+
+## Migration Paths
+
+### For Node.js Projects
+
+**No changes required!** Your existing code works as-is.
+
+```typescript
+// ✅ This still works
+import { OrbitCosmos } from '@gravito/cosmos'
+
+const cosmos = new OrbitCosmos({
+  defaultLocale: 'zh-TW',
+  supportedLocales: ['zh-TW', 'en'],
+  lazyLoad: {
+    baseDir: './lang'
+  }
+})
+```
+
+### For Edge Runtime Projects
+
+#### Option 1: Static Translations (Recommended for <100KB)
+
+```typescript
+// Before: Not possible
+// After: Use MemoryLoader
+import { OrbitCosmos, MemoryLoader } from '@gravito/cosmos/edge'
+import en from './lang/en.json'
+import zhTW from './lang/zh-TW.json'
+
+const cosmos = new OrbitCosmos({
+  defaultLocale: 'zh-TW',
+  supportedLocales: ['zh-TW', 'en'],
+  loaders: [
+    new MemoryLoader({
+      translations: { en, 'zh-TW': zhTW }
+    })
+  ]
+})
+```
+
+#### Option 2: Remote API (Recommended for dynamic content)
+
+```typescript
+import { OrbitCosmos, RemoteLoader } from '@gravito/cosmos/edge'
+
+const cosmos = new OrbitCosmos({
+  defaultLocale: 'zh-TW',
+  supportedLocales: ['zh-TW', 'en'],
+  loaders: [
+    new RemoteLoader({
+      url: 'https://api.example.com/i18n/:locale',
+      etagCache: true,
+      retries: 3
+    })
+  ]
+})
+```
+
+#### Option 3: KV Storage (Recommended for Cloudflare/Vercel)
+
+**Cloudflare Workers:**
+
+```typescript
+import { OrbitCosmos, CloudflareKVLoader } from '@gravito/cosmos/edge'
+
+export interface Env {
+  I18N_KV: KVNamespace
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const cosmos = new OrbitCosmos({
+      defaultLocale: 'zh-TW',
+      supportedLocales: ['zh-TW', 'en'],
+      loaders: [
+        new CloudflareKVLoader({
+          namespace: env.I18N_KV
+        })
+      ]
+    })
+
+    // ... use cosmos
+  }
+}
+```
+
+**Vercel Edge Functions:**
+
+```typescript
+import { OrbitCosmos, VercelKVLoader } from '@gravito/cosmos/edge'
+import { kv } from '@vercel/kv'
+
+const cosmos = new OrbitCosmos({
+  defaultLocale: 'zh-TW',
+  supportedLocales: ['zh-TW', 'en'],
+  loaders: [
+    new VercelKVLoader({ kv })
+  ]
+})
+```
+
+## Best Practices
+
+### 1. Use Fallback Chains
+
+Combine loaders for reliability:
+
+```typescript
+import { MemoryLoader, RemoteLoader, CloudflareKVLoader } from '@gravito/cosmos/edge'
+
+const cosmos = new OrbitCosmos({
+  loaders: [
+    new CloudflareKVLoader({ namespace: env.I18N_KV })
+      .fallback(new RemoteLoader({ url: env.I18N_API }))
+      .fallback(new MemoryLoader({ translations: fallbackData }))
+  ]
+})
+```
+
+### 2. Choose the Right Loader
+
+| Scenario | Recommended Loader | Reason |
+|----------|-------------------|--------|
+| Small static translations (<100KB) | MemoryLoader | Fastest, no network |
+| Dynamic CMS translations | RemoteLoader | Real-time updates |
+| Cloudflare Workers | CloudflareKVLoader | Edge-optimized |
+| Vercel Edge | VercelKVLoader | Edge-optimized |
+| Node.js server | FileSystemLoader | Native fs access |
+
+### 3. Optimize Bundle Size
+
+Edge environments have size limits:
+
+```typescript
+// ✅ Good: Import only what you need
+import { OrbitCosmos, MemoryLoader } from '@gravito/cosmos/edge'
+
+// ❌ Avoid: Importing Node.js-only features in Edge
+import { FileSystemLoader } from '@gravito/cosmos/node'
+```
+
+## Deprecated Features
+
+### lazyLoad.loader (Still works, but deprecated)
+
+```typescript
+// ⚠️ Deprecated
+{
+  lazyLoad: {
+    baseDir: './lang',
+    loader: customLoaderFn
+  }
+}
+
+// ✅ Recommended
+{
+  loaders: [
+    new FileSystemLoader({ baseDir: './lang' })
+  ]
+}
+```
+
+## Troubleshooting
+
+### Error: "FileSystemLoader requires Node.js"
+
+**Cause**: Using FileSystemLoader in Edge Runtime
+
+**Solution**: Use MemoryLoader, RemoteLoader, or EdgeKVLoader
+
+```typescript
+// ❌ Wrong
+import { FileSystemLoader } from '@gravito/cosmos/edge'
+
+// ✅ Correct
+import { MemoryLoader } from '@gravito/cosmos/edge'
+```
+
+### Warning: "HMR is not supported in Edge Runtime"
+
+**Cause**: HMRWatcher is Node.js-only
+
+**Solution**: Use RemoteLoader with ETag caching for dynamic updates
+
+```typescript
+// Edge Runtime alternative to HMR
+new RemoteLoader({
+  url: 'https://api.example.com/i18n/:locale',
+  etagCache: true // Automatically refetches when content changes
+})
+```
+
+### Translations not loading
+
+**Debug steps:**
+
+1. Check loader configuration
+2. Verify translations are uploaded (for KV loaders)
+3. Check network requests (for RemoteLoader)
+4. Enable verbose logging
+
+```typescript
+const loader = new RemoteLoader({
+  url: 'https://api.example.com/i18n/:locale',
+  // Add console.log in load method for debugging
+})
+
+console.log('Testing load:', await loader.load('en'))
+```
+
+## Examples
+
+### Cloudflare Workers Complete Example
+
+```typescript
+import { OrbitCosmos, CloudflareKVLoader, MemoryLoader } from '@gravito/cosmos/edge'
+
+export interface Env {
+  I18N_KV: KVNamespace
+}
+
+// Fallback translations
+const fallback = {
+  en: { error: 'An error occurred' },
+  'zh-TW': { error: '發生錯誤' }
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const cosmos = new OrbitCosmos({
+      defaultLocale: 'zh-TW',
+      supportedLocales: ['zh-TW', 'en'],
+      loaders: [
+        new CloudflareKVLoader({ namespace: env.I18N_KV })
+          .fallback(new MemoryLoader({ translations: fallback }))
+      ]
+    })
+
+    const i18n = cosmos.clone('zh-TW')
+    await i18n.ensureLocale('zh-TW')
+
+    return new Response(i18n.t('welcome'))
+  }
+}
+```
+
+### Vercel Edge Functions Complete Example
+
+```typescript
+import { OrbitCosmos, VercelKVLoader } from '@gravito/cosmos/edge'
+import { kv } from '@vercel/kv'
+
+const cosmos = new OrbitCosmos({
+  defaultLocale: 'zh-TW',
+  supportedLocales: ['zh-TW', 'en'],
+  loaders: [
+    new VercelKVLoader({ kv, prefix: 'i18n' })
+  ]
+})
+
+export async function GET(request: Request) {
+  const url = new URL(request.url)
+  const locale = url.searchParams.get('lang') || 'zh-TW'
+
+  const i18n = cosmos.clone(locale)
+  await i18n.ensureLocale(locale)
+
+  return new Response(JSON.stringify({
+    message: i18n.t('welcome'),
+    locale: i18n.getLocale()
+  }))
+}
+```
+
+## FAQ
+
+**Q: Do I need to update my code for v2.0?**
+A: No, v2.0 is fully backward compatible.
+
+**Q: Can I use FileSystemLoader in Edge Runtime?**
+A: No, use MemoryLoader, RemoteLoader, or EdgeKVLoader instead.
+
+**Q: How do I upload translations to KV storage?**
+A: See the CloudflareKVLoader and VercelKVLoader documentation for upload scripts.
+
+**Q: What's the performance difference between loaders?**
+A: MemoryLoader (fastest) > KV Loaders (fast) > RemoteLoader (depends on network)
+
+**Q: Can I mix Node.js and Edge loaders?**
+A: In Node.js, yes. In Edge, only Edge-compatible loaders work.
+
+## Support
+
+- Documentation: [README.md](./README.md)
+- Architecture: [docs/architecture/cosmos.md](../../docs/architecture/cosmos.md)
+- Issues: [GitHub Issues](https://github.com/gravito-framework/gravito/issues)

package/README.md

@@ -1,8 +1,18 @@
-# @gravito/cosmos
+# @gravito/cosmos 🌌
 
-> Lightweight Internationalization (i18n) Orbit for Gravito.
+> Lightweight, high-performance Internationalization (i18n) Orbit for the Gravito framework.
 
-Provides simple JSON-based localization support for your Gravito application, with seamless integration into Photon context.
+`@gravito/cosmos` brings seamless localization support to your Gravito applications. It features request-scoped i18n instances, lazy loading of translation files, parameter replacement, and flexible locale detection.
+
+## ✨ Features
+
+- **🚀 Performance-First**: Highly optimized translation resolution with internal caching.
+- **🛡️ Type-Safe**: Support for type-safe translation keys using TypeScript generics.
+- **🔄 Request-Scoped**: Clones i18n instances per request to maintain locale state without resource duplication.
+- **📂 Lazy Loading**: Load translation files from the filesystem only when needed.
+- **🔗 Flexible Fallbacks**: Define custom fallback chains and missing key strategies.
+- **🌍 Pluralization**: Integrated support for `Intl.PluralRules` based pluralization.
+- **📡 Auto-Detection**: Detects locale from Route Params, Query Strings, or `Accept-Language` headers.
 
 ## 📦 Installation
 
@@ -12,55 +22,105 @@ bun add @gravito/cosmos
 
 ## 🚀 Quick Start
 
-1.  **Register the Orbit**:
-    ```typescript
-    import { PlanetCore } from '@gravito/core';
-    import { OrbitI18n } from '@gravito/cosmos';
-
-    const core = new PlanetCore();
-
-    core.boot({
-      orbits: [OrbitI18n],
-      config: {
-        i18n: {
-          defaultLocale: 'en',
-          fallbackLocale: 'en',
-          path: './lang' // Path to your locale JSON files
-        }
-      }
-    });
-    ```
-
-2.  **Create Locale Files**:
-    Create `./lang/en.json` and `./lang/zh-TW.json`:
-    ```json
-    // en.json
-    {
-      "welcome": "Welcome, {name}!"
+### 1. Register the Orbit
+
+Add `OrbitCosmos` to your PlanetCore configuration:
+
+```typescript
+import { PlanetCore } from '@gravito/core';
+import { OrbitCosmos } from '@gravito/cosmos';
+
+const core = new PlanetCore({
+  config: {
+    // Optional static translations
+    translations: {
+      en: { welcome: 'Welcome, :name!' },
+      'zh-TW': { welcome: '歡迎，:name！' }
     }
-    ```
+  }
+});
+
+core.addOrbit(new OrbitCosmos({
+  defaultLocale: 'en',
+  supportedLocales: ['en', 'zh-TW'],
+  // Optional: configure lazy loading from a directory
+  lazyLoad: {
+    baseDir: './lang'
+  }
+}));
+
+await core.bootstrap();
+```
 
-3.  **Use in Routes**:
-    ```typescript
-    app.get('/', (c) => {
-      const t = c.get('t');
-      return c.text(t('welcome', { name: 'Carl' }));
-    });
-    ```
+### 2. Create Locale Files (If using lazy loading)
+
+Create `./lang/en.json`:
+```json
+{
+  "auth": {
+    "login_success": "Welcome back!",
+    "failed": "Invalid credentials."
+  },
+  "items": {
+    "count": {
+      "zero": "No items found",
+      "one": "Found :count item",
+      "other": "Found :count items"
+    }
+  }
+}
+```
 
-## ✨ Features
+### 3. Use in Routes
 
--   **Context Injection**: Automatically injects `t()` helper into Photon context.
--   **Parameter Replacement**: Supports `{key}` style parameter replacement.
--   **Locale Detection**: Automatically detects locale from `Accept-Language` header or query parameter `?lang=`.
--   **Fallback**: gracefully falls back to default locale if key is missing.
+The `i18n` service is automatically injected into the context:
 
-## 📚 API
+```typescript
+app.get('/hello', (c) => {
+  const t = c.get('i18n').t;
+  return c.text(t('welcome', { name: 'Carl' }));
+});
 
-### `t(key: string, params?: Record<string, any>): string`
+// Pluralization
+app.get('/items', (c) => {
+  const i18n = c.get('i18n');
+  return c.text(i18n.t('items.count', { count: 5 })); // "Found 5 items"
+});
+```
 
-Main translation helper function.
+## 📚 Core Concepts
+
+### I18nManager
+The central hub that holds shared configuration and translation resources. It handles the heavy lifting of loading files and resolving keys.
+
+### I18nInstance
+A lightweight, request-scoped object that holds the current locale. It delegates to the `I18nManager` for translations.
+
+### Locale Detectors
+Built-in detectors allow automatic locale selection:
+- `RouteParamDetector`: Looks for `:locale` in route parameters.
+- `QueryDetector`: Looks for `?lang=` in the URL.
+- `HeaderDetector`: Uses the `Accept-Language` header.
+
+## 🛠️ Configuration
+
+```typescript
+export interface I18nConfig {
+  defaultLocale: string;
+  supportedLocales: string[];
+  translations?: Record<string, TranslationMap>;
+  lazyLoad?: {
+    baseDir: string;
+    preload?: string[];
+  };
+  fallback?: {
+    fallbackChain?: Record<string, string[]>;
+    onMissingKey?: 'key' | 'empty' | 'throw' | ((key: string, locale: string) => string);
+    warnOnMissing?: boolean;
+  };
+}
+```
 
 ## License
 
-MIT
+MIT © Carl Lee

package/README.zh-TW.md

@@ -1,46 +1,126 @@
-# @gravito/cosmos
+# @gravito/cosmos 🌌
 
-> Gravito 的輕量 i18n 模組，提供 JSON 檔案式在地化。
+> 為 Gravito 框架設計的輕量級、高效能國際化 (i18n) 擴展。
 
-## 安裝
+`@gravito/cosmos` 為您的 Gravito 應用程式提供無縫的在地化支援。具備請求級別的 i18n 實例、翻譯檔案懶加載、參數替換以及靈活的語言偵測功能。
+
+## ✨ 特性
+
+- **🚀 效能優先**：高度優化的翻譯查找與內部快取機制。
+- **🛡️ 類型安全**：支援 TypeScript 泛型，提供類型安全的翻譯鍵值。
+- **🔄 請求級別實例**：為每個請求克隆輕量實例，保持語言狀態而不重複佔用資源。
+- **📂 懶加載**：僅在需要時從檔案系統載入翻譯檔案。
+- **🔗 靈活的回退機制**：可自定義回退鏈與缺失鍵值的處理策略。
+- **🌍 複數支援**：整合 `Intl.PluralRules` 的複數處理。
+- **📡 自動偵測**：支援從路由參數、查詢字串或 `Accept-Language` 標頭偵測語言。
+
+## 📦 安裝
 
 ```bash
 bun add @gravito/cosmos
 ```
 
-## 快速開始
+## 🚀 快速開始
 
-```typescript
-import { PlanetCore } from '@gravito/core'
-import { OrbitI18n } from '@gravito/cosmos'
+### 1. 註冊 Orbit
 
-const core = new PlanetCore()
+將 `OrbitCosmos` 加入您的 PlanetCore 配置中：
 
-core.boot({
-  orbits: [OrbitI18n],
+```typescript
+import { PlanetCore } from '@gravito/core';
+import { OrbitCosmos } from '@gravito/cosmos';
+
+const core = new PlanetCore({
   config: {
-    i18n: {
-      defaultLocale: 'en',
-      fallbackLocale: 'en',
-      path: './lang'
+    // 可選的靜態翻譯
+    translations: {
+      en: { welcome: 'Welcome, :name!' },
+      'zh-TW': { welcome: '歡迎，:name！' }
     }
   }
-})
+});
+
+core.addOrbit(new OrbitCosmos({
+  defaultLocale: 'en',
+  supportedLocales: ['en', 'zh-TW'],
+  // 可選：配置語言檔案目錄
+  lazyLoad: {
+    baseDir: './lang'
+  }
+}));
+
+await core.bootstrap();
 ```
 
-建立 `./lang/en.json`:
+### 2. 建立語言檔案 (若使用懶加載)
 
+建立 `./lang/en.json`:
 ```json
 {
-  "welcome": "Welcome, {name}!"
+  "auth": {
+    "login_success": "Welcome back!",
+    "failed": "Invalid credentials."
+  },
+  "items": {
+    "count": {
+      "zero": "No items found",
+      "one": "Found :count item",
+      "other": "Found :count items"
+    }
+  }
 }
 ```
 
-在路由中使用：
+### 3. 在路由中使用
+
+`i18n` 服務會自動注入到上下文 (Context) 中：
 
 ```typescript
-app.get('/', (c) => {
-  const t = c.get('t')
-  return c.text(t('welcome', { name: 'Carl' }))
-})
+app.get('/hello', (c) => {
+  const t = c.get('i18n').t;
+  return c.text(t('welcome', { name: 'Carl' }));
+});
+
+// 複數處理
+app.get('/items', (c) => {
+  const i18n = c.get('i18n');
+  return c.text(i18n.t('items.count', { count: 5 })); // "Found 5 items"
+});
 ```
+
+## 📚 核心概念
+
+### I18nManager
+核心管理中心，持有共享配置與翻譯資源。負責載入檔案、處理翻譯邏輯、回退策略與快取。
+
+### I18nInstance
+輕量級的請求範圍物件，持有當前的語言狀態。實際翻譯邏輯委託給 `I18nManager` 執行。
+
+### 語言偵測器 (Locale Detectors)
+內建多種偵測器：
+- `RouteParamDetector`：從路由參數 `:locale` 獲取。
+- `QueryDetector`：從 URL 查詢字串 `?lang=` 獲取。
+- `HeaderDetector`：從 `Accept-Language` HTTP 標頭獲取。
+
+## 🛠️ 配置選項
+
+```typescript
+export interface I18nConfig {
+  defaultLocale: string;
+  supportedLocales: string[];
+  translations?: Record<string, TranslationMap>;
+  lazyLoad?: {
+    baseDir: string;
+    preload?: string[];
+  };
+  fallback?: {
+    fallbackChain?: Record<string, string[]>;
+    onMissingKey?: 'key' | 'empty' | 'throw' | ((key: string, locale: string) => string);
+    warnOnMissing?: boolean;
+  };
+}
+```
+
+## License
+
+MIT © Carl Lee