@gravito/cosmos 1.0.0-alpha.2

package/README.md

@@ -0,0 +1,66 @@
+# @gravito/cosmos
+
+> Lightweight Internationalization (i18n) Orbit for Gravito.
+
+Provides simple JSON-based localization support for your Gravito application, with seamless integration into Hono context.
+
+## 📦 Installation
+
+```bash
+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}!"
+    }
+    ```
+
+3.  **Use in Routes**:
+    ```typescript
+    app.get('/', (c) => {
+      const t = c.get('t');
+      return c.text(t('welcome', { name: 'Carl' }));
+    });
+    ```
+
+## ✨ Features
+
+-   **Context Injection**: Automatically injects `t()` helper into Hono 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.
+
+## 📚 API
+
+### `t(key: string, params?: Record<string, any>): string`
+
+Main translation helper function.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,125 @@
+// src/I18nService.ts
+class I18nManager {
+  config;
+  _locale;
+  translations = {};
+  constructor(config) {
+    this.config = config;
+    this._locale = config.defaultLocale;
+    if (config.translations) {
+      this.translations = config.translations;
+    }
+  }
+  get locale() {
+    return this._locale;
+  }
+  set locale(value) {
+    this.setLocale(value);
+  }
+  setLocale(locale) {
+    if (this.config.supportedLocales.includes(locale)) {
+      this._locale = locale;
+    }
+  }
+  getLocale() {
+    return this._locale;
+  }
+  addResource(locale, translations) {
+    this.translations[locale] = {
+      ...this.translations[locale] || {},
+      ...translations
+    };
+  }
+  t(key, replacements) {
+    const keys = key.split(".");
+    let value = this.translations[this._locale];
+    for (const k of keys) {
+      if (value && typeof value === "object" && k in value) {
+        value = value[k];
+      } else {
+        value = undefined;
+        break;
+      }
+    }
+    if (value === undefined && this._locale !== this.config.defaultLocale) {
+      let fallbackValue = this.translations[this.config.defaultLocale];
+      for (const k of keys) {
+        if (fallbackValue && typeof fallbackValue === "object" && k in fallbackValue) {
+          fallbackValue = fallbackValue[k];
+        } else {
+          fallbackValue = undefined;
+          break;
+        }
+      }
+      value = fallbackValue;
+    }
+    if (value === undefined || typeof value !== "string") {
+      return key;
+    }
+    if (replacements) {
+      for (const [search, replace] of Object.entries(replacements)) {
+        value = value.replace(new RegExp(`:${search}`, "g"), String(replace));
+      }
+    }
+    return value;
+  }
+  has(key) {
+    return this.t(key) !== key;
+  }
+}
+var localeMiddleware = (i18n) => {
+  return async (c, next) => {
+    const paramLocale = c.req.param("locale");
+    if (paramLocale) {
+      i18n.setLocale(paramLocale);
+    }
+    c.set("i18n", i18n);
+    await next();
+  };
+};
+// src/loader.ts
+import { readdir, readFile } from "node:fs/promises";
+import { join, parse } from "node:path";
+async function loadTranslations(directory) {
+  const translations = {};
+  try {
+    const files = await readdir(directory);
+    for (const file of files) {
+      if (!file.endsWith(".json")) {
+        continue;
+      }
+      const locale = parse(file).name;
+      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);
+      }
+    }
+  } catch (_e) {
+    console.warn(`[Orbit-I18n] Could not load translations from ${directory}. Directory might not exist.`);
+  }
+  return translations;
+}
+
+// src/index.ts
+class I18nOrbit {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  install(core) {
+    const i18n = new I18nManager(this.config);
+    core.adapter.use("*", async (c, next) => {
+      c.set("i18n", i18n);
+      await next();
+    });
+    core.logger.info(`I18n Orbit initialized with locale: ${this.config.defaultLocale}`);
+  }
+}
+export {
+  localeMiddleware,
+  loadTranslations,
+  I18nOrbit,
+  I18nManager
+};

package/dist/src/index.js

@@ -0,0 +1,125 @@
+// src/I18nService.ts
+class I18nManager {
+  config;
+  _locale;
+  translations = {};
+  constructor(config) {
+    this.config = config;
+    this._locale = config.defaultLocale;
+    if (config.translations) {
+      this.translations = config.translations;
+    }
+  }
+  get locale() {
+    return this._locale;
+  }
+  set locale(value) {
+    this.setLocale(value);
+  }
+  setLocale(locale) {
+    if (this.config.supportedLocales.includes(locale)) {
+      this._locale = locale;
+    }
+  }
+  getLocale() {
+    return this._locale;
+  }
+  addResource(locale, translations) {
+    this.translations[locale] = {
+      ...this.translations[locale] || {},
+      ...translations
+    };
+  }
+  t(key, replacements) {
+    const keys = key.split(".");
+    let value = this.translations[this._locale];
+    for (const k of keys) {
+      if (value && typeof value === "object" && k in value) {
+        value = value[k];
+      } else {
+        value = undefined;
+        break;
+      }
+    }
+    if (value === undefined && this._locale !== this.config.defaultLocale) {
+      let fallbackValue = this.translations[this.config.defaultLocale];
+      for (const k of keys) {
+        if (fallbackValue && typeof fallbackValue === "object" && k in fallbackValue) {
+          fallbackValue = fallbackValue[k];
+        } else {
+          fallbackValue = undefined;
+          break;
+        }
+      }
+      value = fallbackValue;
+    }
+    if (value === undefined || typeof value !== "string") {
+      return key;
+    }
+    if (replacements) {
+      for (const [search, replace] of Object.entries(replacements)) {
+        value = value.replace(new RegExp(`:${search}`, "g"), String(replace));
+      }
+    }
+    return value;
+  }
+  has(key) {
+    return this.t(key) !== key;
+  }
+}
+var localeMiddleware = (i18n) => {
+  return async (c, next) => {
+    const paramLocale = c.req.param("locale");
+    if (paramLocale) {
+      i18n.setLocale(paramLocale);
+    }
+    c.set("i18n", i18n);
+    await next();
+  };
+};
+// src/loader.ts
+import { readdir, readFile } from "node:fs/promises";
+import { join, parse } from "node:path";
+async function loadTranslations(directory) {
+  const translations = {};
+  try {
+    const files = await readdir(directory);
+    for (const file of files) {
+      if (!file.endsWith(".json")) {
+        continue;
+      }
+      const locale = parse(file).name;
+      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);
+      }
+    }
+  } catch (_e) {
+    console.warn(`[Orbit-I18n] Could not load translations from ${directory}. Directory might not exist.`);
+  }
+  return translations;
+}
+
+// src/index.ts
+class I18nOrbit {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  install(core) {
+    const i18n = new I18nManager(this.config);
+    core.app.use("*", async (c, next) => {
+      c.set("i18n", i18n);
+      await next();
+    });
+    core.logger.info(`I18n Orbit initialized with locale: ${this.config.defaultLocale}`);
+  }
+}
+export {
+  localeMiddleware,
+  loadTranslations,
+  I18nOrbit,
+  I18nManager
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@gravito/cosmos",
+  "version": "1.0.0-alpha.2",
+  "description": "Internationalization orbit for Gravito framework",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --external @gravito/core --external hono",
+    "test": "bun test"
+  },
+  "keywords": [
+    "gravito",
+    "orbit",
+    "i18n",
+    "internationalization"
+  ],
+  "author": "Carl Lee <carllee0520@gmail.com>",
+  "license": "MIT",
+  "peerDependencies": {
+    "gravito-core": "1.0.0-beta.2",
+    "hono": "^4.0.0"
+  },
+  "devDependencies": {
+    "bun-types": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/gravito-framework/gravito#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gravito-framework/gravito.git",
+    "directory": "packages/cosmos"
+  }
+}

package/src/I18nService.ts

@@ -0,0 +1,139 @@
+import type { MiddlewareHandler } from 'hono'
+
+export interface I18nConfig {
+  defaultLocale: string
+  supportedLocales: string[]
+  // Path to translation files, or a Record of translations
+  // If undefined, it will look into `resources/lang` by default (conceptually, handled by loader)
+  translations?: Record<string, Record<string, string>>
+}
+
+export interface I18nService {
+  locale: string
+  setLocale(locale: string): void
+  getLocale(): string
+  t(key: string, replacements?: Record<string, string | number>): string
+  has(key: string): boolean
+}
+
+export class I18nManager implements I18nService {
+  private _locale: string
+  private translations: Record<string, Record<string, string>> = {}
+
+  constructor(private config: I18nConfig) {
+    this._locale = config.defaultLocale
+    if (config.translations) {
+      this.translations = config.translations
+    }
+  }
+
+  get locale(): string {
+    return this._locale
+  }
+
+  set locale(value: string) {
+    this.setLocale(value)
+  }
+
+  setLocale(locale: string) {
+    if (this.config.supportedLocales.includes(locale)) {
+      this._locale = locale
+    }
+  }
+
+  getLocale(): string {
+    return this._locale
+  }
+
+  /**
+   * Add translations for a locale
+   */
+  addResource(locale: string, translations: Record<string, string>) {
+    this.translations[locale] = {
+      ...(this.translations[locale] || {}),
+      ...translations,
+    }
+  }
+
+  /**
+   * Translation helper
+   * t('messages.welcome', { name: 'Carl' })
+   * Supports nested keys via dot notation: t('auth.errors.invalid')
+   */
+  t(key: string, replacements?: Record<string, string | number>): string {
+    const keys = key.split('.')
+    let value: any = this.translations[this._locale]
+
+    // Fallback to default locale if not found in current locale?
+    // Implementation: Try current locale, then fallback.
+
+    // 1. Try current locale
+    for (const k of keys) {
+      if (value && typeof value === 'object' && k in value) {
+        value = value[k]
+      } else {
+        value = undefined
+        break
+      }
+    }
+
+    // 2. If not found, try fallback (defaultLocale)
+    if (value === undefined && this._locale !== this.config.defaultLocale) {
+      let fallbackValue: any = this.translations[this.config.defaultLocale]
+      for (const k of keys) {
+        if (fallbackValue && typeof fallbackValue === 'object' && k in fallbackValue) {
+          fallbackValue = fallbackValue[k]
+        } else {
+          fallbackValue = undefined
+          break
+        }
+      }
+      value = fallbackValue
+    }
+
+    if (value === undefined || typeof value !== 'string') {
+      return key // Return key if not found
+    }
+
+    // 3. Replacements
+    if (replacements) {
+      for (const [search, replace] of Object.entries(replacements)) {
+        value = value.replace(new RegExp(`:${search}`, 'g'), String(replace))
+      }
+    }
+
+    return value
+  }
+
+  has(key: string): boolean {
+    // Simplistic check
+    return this.t(key) !== key
+  }
+}
+
+/**
+ * Locale Middleware
+ *
+ * Detects locale from:
+ * 1. Route Parameter (e.g. /:locale/foo) - Recommended for SEO
+ * 2. Header (Accept-Language) - Recommended for APIs
+ */
+export const localeMiddleware = (i18n: I18nService): MiddlewareHandler => {
+  return async (c, next) => {
+    // 1. Check for route param 'locale'
+    const paramLocale = c.req.param('locale')
+    if (paramLocale) {
+      i18n.setLocale(paramLocale)
+    }
+
+    // 2. Inject into context (using 'any' for now, or augment PlanetCore variables later)
+    c.set('i18n', i18n)
+
+    // 3. Share with View layer (if Orbit View is present)
+    // Assuming 'view' service might look at context variables or we explicitly pass it
+    // For Inertia, we might want to share it as a prop.
+    // This part depends on how the user sets up their detailed pipeline, but setting it in 'c' is the start.
+
+    await next()
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+import type { GravitoOrbit, PlanetCore } from 'gravito-core'
+import { type I18nConfig, I18nManager, type I18nService } from './I18nService'
+
+declare module 'gravito-core' {
+  interface Variables {
+    i18n: I18nService
+  }
+}
+
+export class I18nOrbit implements GravitoOrbit {
+  constructor(private config: I18nConfig) {}
+
+  install(core: PlanetCore): void {
+    const i18n = new I18nManager(this.config)
+
+    // Register globally if needed, or just prepare it to be used.
+    // There isn't a global "services" container in PlanetCore yet other than 'Variables' injected via Config/Context.
+    // Ideally we attach it to the core instance or inject it into every request.
+
+    // Inject into every request
+    core.adapter.use('*', async (c, next) => {
+      c.set('i18n', i18n)
+      await next()
+    })
+
+    // Register a helper if using Orbit View (View Rendering)
+    // We can check if 'view' exists or we can register a global view helper if that API exists.
+    // For now, context injection is sufficient.
+
+    core.logger.info(`I18n Orbit initialized with locale: ${this.config.defaultLocale}`)
+  }
+}
+
+export * from './I18nService'
+export * from './loader'

package/src/loader.ts

@@ -0,0 +1,43 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { join, parse } from 'node:path'
+
+/**
+ * Load translations from a directory
+ * Structure:
+ * /lang
+ *   /en.json -> { "welcome": "Hello" }
+ *   /zh.json -> { "welcome": "Hello" }
+ *   /en/auth.json -> { "failed": "Login failed" } (Optional deep structure, maybe later)
+ *
+ * For now, we support flat JSON files per locale: en.json, zh.json
+ */
+export async function loadTranslations(
+  directory: string
+): Promise<Record<string, Record<string, string>>> {
+  const translations: Record<string, Record<string, string>> = {}
+
+  try {
+    const files = await readdir(directory)
+
+    for (const file of files) {
+      if (!file.endsWith('.json')) {
+        continue
+      }
+
+      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)
+      }
+    }
+  } catch (_e) {
+    console.warn(
+      `[Orbit-I18n] Could not load translations from ${directory}. Directory might not exist.`
+    )
+  }
+
+  return translations
+}

package/tests/manager.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'bun:test'
+import { I18nManager } from '../src/index'
+
+describe('Orbit I18n Manager', () => {
+  const _config = {
+    defaultLocale: 'en',
+    supportedLocales: ['en', 'zh', 'jp'],
+    translations: {
+      en: {
+        welcome: 'Welcome',
+        'auth.failed': 'Start Login Failed', // Nested key test mock
+        nested: 'Start Nested',
+      },
+      zh: {
+        welcome: '歡迎',
+      },
+    },
+  }
+
+  // Manually constructing nested object for test since our mock config above is flat strings
+  // But our I18nManager logic supports object traversal. Let's fix the mock data to be object structure if we want to test traversal properly,
+  // OR we fix our Loader to flatten everything?
+  // Gravito's Manager currently supports object traversal: value[k].
+  // Let's use proper object structure for 'auth' in 'en'.
+  // Redefining config for clarity.
+  const nestedConfig = {
+    defaultLocale: 'en',
+    supportedLocales: ['en', 'zh'],
+    translations: {
+      en: {
+        title: 'Hello',
+        auth: {
+          // @ts-expect-error
+          failed: 'Failed Login',
+        } as any,
+      },
+      zh: {
+        title: '你好',
+      },
+    },
+  }
+
+  test('it selects default locale initially', () => {
+    const i18n = new I18nManager(nestedConfig as any)
+    expect(i18n.locale).toBe('en')
+  })
+
+  test('it can change locale', () => {
+    const i18n = new I18nManager(nestedConfig as any)
+    i18n.locale = 'zh'
+    expect(i18n.locale).toBe('zh')
+
+    // Unsupported locale should be ignored (based on our implementation logic?)
+    // Let's check implementation: if (supported.includes) ...
+    i18n.locale = 'fr'
+    expect(i18n.locale).toBe('zh')
+  })
+
+  test('it translates simple keys', () => {
+    const i18n = new I18nManager(nestedConfig as any)
+    expect(i18n.t('title')).toBe('Hello')
+
+    i18n.locale = 'zh'
+    expect(i18n.t('title')).toBe('你好')
+  })
+
+  test('it handles fallback to default locale', () => {
+    const i18n = new I18nManager(nestedConfig as any)
+    i18n.locale = 'zh'
+
+    // 'auth.failed' is only in EN
+    expect(i18n.t('auth.failed')).toBe('Failed Login')
+  })
+
+  test('it returns key if not found', () => {
+    const i18n = new I18nManager(nestedConfig as any)
+    expect(i18n.t('missing.key')).toBe('missing.key')
+  })
+
+  test('it supports replacements', () => {
+    const i18n = new I18nManager({
+      defaultLocale: 'en',
+      supportedLocales: ['en'],
+      translations: {
+        en: {
+          greet: 'Hello :name',
+        },
+      },
+    })
+
+    expect(i18n.t('greet', { name: 'Carl' })).toBe('Hello Carl')
+  })
+})

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+    "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"
+    ]
+}