@gravito/cosmos 1.0.0-alpha.3 → 1.0.0-alpha.5

package/README.zh-TW.md

@@ -0,0 +1,46 @@
+# @gravito/cosmos
+
+> Gravito 的輕量 i18n 模組，提供 JSON 檔案式在地化。
+
+## 安裝
+
+```bash
+bun add @gravito/cosmos
+```
+
+## 快速開始
+
+```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'
+    }
+  }
+})
+```
+
+建立 `./lang/en.json`:
+
+```json
+{
+  "welcome": "Welcome, {name}!"
+}
+```
+
+在路由中使用：
+
+```typescript
+app.get('/', (c) => {
+  const t = c.get('t')
+  return c.text(t('welcome', { name: 'Carl' }))
+})
+```

package/dist/index.js

@@ -106,7 +106,7 @@ class I18nManager {
     return value;
   }
 }
-var localeMiddleware2 = (i18nManager) => {
+var localeMiddleware = (i18nManager) => {
   return async (c, next) => {
     let locale = c.req.param("locale") || c.req.query("lang");
     if (!locale) {
@@ -158,7 +158,7 @@ class I18nOrbit {
   }
 }
 export {
-  localeMiddleware2 as localeMiddleware,
+  localeMiddleware,
   loadTranslations,
   I18nOrbit,
   I18nManager,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/cosmos",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Internationalization orbit for Gravito framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +17,7 @@
   "author": "Carl Lee <carllee0520@gmail.com>",
   "license": "MIT",
   "peerDependencies": {
-    "gravito-core": "1.0.0-beta.2",
+    "gravito-core": "1.0.0-beta.4",
     "hono": "^4.0.0"
   },
   "devDependencies": {

package/src/I18nService.ts

@@ -25,6 +25,12 @@ export interface I18nService {
 export class I18nInstance implements I18nService {
   private _locale: string
 
+  /**
+   * Create a new I18nInstance.
+   *
+   * @param manager - The I18nManager instance.
+   * @param initialLocale - The initial locale for this instance.
+   */
   constructor(
     private manager: I18nManager,
     initialLocale: string
@@ -40,24 +46,53 @@ export class I18nInstance implements I18nService {
     this.setLocale(value)
   }
 
+  /**
+   * Set the current locale.
+   *
+   * @param locale - The locale to set.
+   */
   setLocale(locale: string) {
     if (this.manager.getConfig().supportedLocales.includes(locale)) {
       this._locale = locale
     }
   }
 
+  /**
+   * Get the current locale.
+   *
+   * @returns The current locale string.
+   */
   getLocale(): string {
     return this._locale
   }
 
+  /**
+   * Translate a key.
+   *
+   * @param key - The translation key (e.g., 'messages.welcome').
+   * @param replacements - Optional replacements for parameters in the translation string.
+   * @returns The translated string, or the key if not found.
+   */
   t(key: string, replacements?: Record<string, string | number>): string {
     return this.manager.translate(this._locale, key, replacements)
   }
 
+  /**
+   * Check if a translation key exists.
+   *
+   * @param key - The translation key to check.
+   * @returns True if the key exists, false otherwise.
+   */
   has(key: string): boolean {
     return this.t(key) !== key
   }
 
+  /**
+   * Clone the current instance with a potentially new locale.
+   *
+   * @param locale - Optional new locale for the cloned instance.
+   * @returns A new I18nInstance.
+   */
   clone(locale?: string): I18nService {
     return new I18nInstance(this.manager, locale || this._locale)
   }
@@ -72,6 +107,11 @@ export class I18nManager implements I18nService {
   // Default instance for global usage (e.g. CLI or background jobs)
   private globalInstance: I18nInstance
 
+  /**
+   * Create a new I18nManager.
+   *
+   * @param config - The I18n configuration.
+   */
   constructor(private config: I18nConfig) {
     if (config.translations) {
       this.translations = config.translations
@@ -89,32 +129,72 @@ export class I18nManager implements I18nService {
     this.globalInstance.locale = value
   }
 
+  /**
+   * Set the global locale.
+   *
+   * @param locale - The locale to set.
+   */
   setLocale(locale: string): void {
     this.globalInstance.setLocale(locale)
   }
 
+  /**
+   * Get the global locale.
+   *
+   * @returns The global locale string.
+   */
   getLocale(): string {
     return this.globalInstance.getLocale()
   }
 
+  /**
+   * Translate a key using the global locale.
+   *
+   * @param key - The translation key.
+   * @param replacements - Optional replacements.
+   * @returns The translated string.
+   */
   t(key: string, replacements?: Record<string, string | number>): string {
     return this.globalInstance.t(key, replacements)
   }
 
+  /**
+   * Check if a translation key exists in the global locale.
+   *
+   * @param key - The translation key.
+   * @returns True if found.
+   */
   has(key: string): boolean {
     return this.globalInstance.has(key)
   }
 
+  /**
+   * Clone the global instance.
+   *
+   * @param locale - Optional locale for the clone.
+   * @returns A new I18nInstance.
+   */
   clone(locale?: string): I18nService {
     return new I18nInstance(this, locale || this.config.defaultLocale)
   }
 
   // --- Manager Internal API ---
 
+  /**
+   * Get the I18n configuration.
+   *
+   * @returns The configuration object.
+   */
   getConfig(): I18nConfig {
     return this.config
   }
 
+  /**
+   * Add a resource bundle for a specific locale.
+   *
+   * @param locale - The locale string.
+   * @param translations - The translations object.
+   */
   addResource(locale: string, translations: Record<string, string>) {
     this.translations[locale] = {
       ...(this.translations[locale] || {}),
@@ -125,11 +205,7 @@ export class I18nManager implements I18nService {
   /**
    * Internal translation logic used by instances
    */
-  translate(
-    locale: string,
-    key: string,
-    replacements?: Record<string, string | number>
-  ): string {
+  translate(locale: string, key: string, replacements?: Record<string, string | number>): string {
     const keys = key.split('.')
     let value: any = this.translations[locale]
 

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { GravitoOrbit, PlanetCore } from 'gravito-core'
-import { type I18nConfig, I18nManager, type I18nService } from './I18nService'
+import { type I18nConfig, I18nManager, type I18nService, localeMiddleware } from './I18nService'
 
 declare module 'gravito-core' {
   interface Variables {