@objectstack/service-i18n 3.2.5 → 3.2.7

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/service-i18n@3.2.5 build /home/runner/work/spec/spec/packages/services/service-i18n
+> @objectstack/service-i18n@3.2.7 build /home/runner/work/spec/spec/packages/services/service-i18n
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.js     3.19 KB
-ESM dist/index.js.map 9.54 KB
-ESM ⚡️ Build success in 77ms
-CJS dist/index.cjs     4.85 KB
-CJS dist/index.cjs.map 9.95 KB
-CJS ⚡️ Build success in 81ms
+CJS dist/index.cjs     8.08 KB
+CJS dist/index.cjs.map 17.20 KB
+CJS ⚡️ Build success in 73ms
+ESM dist/index.js     6.41 KB
+ESM dist/index.js.map 16.79 KB
+ESM ⚡️ Build success in 84ms
 DTS Build start
-DTS ⚡️ Build success in 12649ms
-DTS dist/index.d.ts  3.29 KB
-DTS dist/index.d.cts 3.29 KB
+DTS ⚡️ Build success in 14439ms
+DTS dist/index.d.ts  4.41 KB
+DTS dist/index.d.cts 4.41 KB

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @objectstack/service-i18n
 
+## 3.2.7
+
+### Patch Changes
+
+- @objectstack/spec@3.2.7
+- @objectstack/core@3.2.7
+
+## 3.2.6
+
+### Patch Changes
+
+- 83151bc: fix i18n
+  - @objectstack/spec@3.2.6
+  - @objectstack/core@3.2.6
+
 ## 3.2.5
 
 ### Patch Changes

package/dist/index.cjs

@@ -124,6 +124,7 @@ var I18nServicePlugin = class {
     this.name = "com.objectstack.service.i18n";
     this.version = "1.0.0";
     this.type = "standard";
+    this.i18n = null;
     this.options = options;
   }
   async init(ctx) {
@@ -132,12 +133,101 @@ var I18nServicePlugin = class {
       localesDir: this.options.localesDir,
       fallbackLocale: this.options.fallbackLocale
     };
-    const i18n = new FileI18nAdapter(adapterOptions);
-    ctx.registerService("i18n", i18n);
+    this.i18n = new FileI18nAdapter(adapterOptions);
+    ctx.registerService("i18n", this.i18n);
     ctx.logger.info(
-      `I18nServicePlugin: registered file-based i18n adapter (default: ${i18n.getDefaultLocale()})`
+      `I18nServicePlugin: registered file-based i18n adapter (default: ${this.i18n.getDefaultLocale?.() ?? "en"})`
     );
   }
+  async start(ctx) {
+    if (this.options.registerRoutes !== false) {
+      ctx.hook("kernel:ready", async () => {
+        let httpServer = null;
+        try {
+          httpServer = ctx.getService("http-server");
+        } catch {
+        }
+        if (httpServer) {
+          this.registerI18nRoutes(httpServer, ctx);
+        } else {
+          ctx.logger.warn(
+            'No HTTP server available \u2014 i18n routes not registered. i18n service is still available programmatically via kernel.getService("i18n").'
+          );
+        }
+      });
+    }
+  }
+  /**
+   * Register i18n REST routes with the HTTP server.
+   *
+   * Routes:
+   * - GET /api/v1/i18n/locales           → list available locales
+   * - GET /api/v1/i18n/translations/:locale → get translations for a locale
+   * - GET /api/v1/i18n/labels/:object/:locale → get field labels for an object
+   */
+  registerI18nRoutes(httpServer, ctx) {
+    if (!this.i18n) return;
+    const basePath = this.options.basePath || "/api/v1/i18n";
+    const i18n = this.i18n;
+    httpServer.get(`${basePath}/locales`, async (_req, res) => {
+      try {
+        const locales = i18n.getLocales();
+        const defaultLocale = i18n.getDefaultLocale?.() ?? "en";
+        res.json({
+          data: {
+            locales: locales.map((code) => ({
+              code,
+              label: code,
+              isDefault: code === defaultLocale
+            }))
+          }
+        });
+      } catch (error) {
+        res.status(500).json({ error: error.message });
+      }
+    });
+    httpServer.get(`${basePath}/translations/:locale`, async (req, res) => {
+      try {
+        const locale = req.params.locale;
+        if (!locale) {
+          res.status(400).json({ error: "Missing locale parameter" });
+          return;
+        }
+        const translations = i18n.getTranslations(locale);
+        res.json({ data: { locale, translations } });
+      } catch (error) {
+        res.status(500).json({ error: error.message });
+      }
+    });
+    httpServer.get(`${basePath}/labels/:object/:locale`, async (req, res) => {
+      try {
+        const objectName = req.params.object;
+        const locale = req.params.locale;
+        if (!objectName || !locale) {
+          res.status(400).json({ error: "Missing object or locale parameter" });
+          return;
+        }
+        const hasGetFieldLabels = "getFieldLabels" in i18n && typeof i18n["getFieldLabels"] === "function";
+        if (hasGetFieldLabels) {
+          const labels = i18n.getFieldLabels(objectName, locale);
+          res.json({ data: { object: objectName, locale, labels } });
+        } else {
+          const translations = i18n.getTranslations(locale);
+          const prefix = `o.${objectName}.fields.`;
+          const labels = {};
+          for (const [key, value] of Object.entries(translations)) {
+            if (key.startsWith(prefix)) {
+              labels[key.substring(prefix.length)] = value;
+            }
+          }
+          res.json({ data: { object: objectName, locale, labels } });
+        }
+      } catch (error) {
+        res.status(500).json({ error: error.message });
+      }
+    });
+    ctx.logger.info(`I18n routes registered: ${basePath}/locales, ${basePath}/translations/:locale, ${basePath}/labels/:object/:locale`);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/file-i18n-adapter.ts","../src/i18n-service-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport { I18nServicePlugin } from './i18n-service-plugin.js';\nexport type { I18nServicePluginOptions } from './i18n-service-plugin.js';\nexport { FileI18nAdapter } from './file-i18n-adapter.js';\nexport type { FileI18nAdapterOptions } from './file-i18n-adapter.js';\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { II18nService } from '@objectstack/spec/contracts';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\n/**\n * Configuration options for FileI18nAdapter.\n */\nexport interface FileI18nAdapterOptions {\n  /** Default locale (e.g. 'en') */\n  defaultLocale?: string;\n  /** Directory containing locale files (JSON). Each file should be named `{locale}.json`. */\n  localesDir?: string;\n  /** Fallback locale when a key is not found in the requested locale */\n  fallbackLocale?: string;\n}\n\n/**\n * Resolve a nested key in a translations object using dot notation.\n *\n * @param data - Translation data object\n * @param key - Dot-separated key (e.g. 'objects.account.label')\n * @returns The resolved string value, or undefined if not found\n */\nfunction resolveKey(data: Record<string, unknown>, key: string): string | undefined {\n  const parts = key.split('.');\n  let current: unknown = data;\n  for (const part of parts) {\n    if (current == null || typeof current !== 'object') return undefined;\n    current = (current as Record<string, unknown>)[part];\n  }\n  return typeof current === 'string' ? current : undefined;\n}\n\n/**\n * Interpolate parameters into a translated string.\n * Replaces `{{paramName}}` with the corresponding value from params.\n *\n * @param template - Template string with `{{key}}` placeholders\n * @param params - Parameter map\n * @returns Interpolated string\n */\nfunction interpolate(template: string, params: Record<string, unknown>): string {\n  return template.replace(/\\{\\{(\\w+)\\}\\}/g, (_match, key: string) => {\n    return params[key] != null ? String(params[key]) : `{{${key}}}`;\n  });\n}\n\n/**\n * File-based I18n adapter implementing II18nService.\n *\n * Loads JSON translation files from a directory on disk.\n * Each file should be named `{locale}.json` and contain a flat or nested\n * key-value map of translations.\n *\n * Supports:\n * - Dot-notation key resolution (e.g. 'objects.account.label')\n * - Parameter interpolation via `{{paramName}}` syntax\n * - Fallback locale for missing translations\n * - Runtime translation loading via loadTranslations()\n *\n * Suitable for server-side rendering, CLI tools, and development environments.\n *\n * @example\n * ```ts\n * const i18n = new FileI18nAdapter({\n *   defaultLocale: 'en',\n *   localesDir: './i18n',\n *   fallbackLocale: 'en',\n * });\n *\n * i18n.t('objects.account.label', 'zh-CN'); // '客户'\n * i18n.t('greeting', 'en', { name: 'World' }); // 'Hello, World!'\n * ```\n */\nexport class FileI18nAdapter implements II18nService {\n  private readonly translations = new Map<string, Record<string, unknown>>();\n  private defaultLocale: string;\n  private readonly fallbackLocale: string | undefined;\n\n  constructor(options: FileI18nAdapterOptions = {}) {\n    this.defaultLocale = options.defaultLocale ?? 'en';\n    this.fallbackLocale = options.fallbackLocale;\n\n    if (options.localesDir) {\n      this.loadFromDirectory(options.localesDir);\n    }\n  }\n\n  t(key: string, locale: string, params?: Record<string, unknown>): string {\n    // Try requested locale\n    let value = this.resolveFromLocale(key, locale);\n\n    // Try fallback locale\n    if (value === undefined && this.fallbackLocale && this.fallbackLocale !== locale) {\n      value = this.resolveFromLocale(key, this.fallbackLocale);\n    }\n\n    // Return key if not found\n    if (value === undefined) return key;\n\n    // Interpolate parameters\n    if (params && Object.keys(params).length > 0) {\n      return interpolate(value, params);\n    }\n\n    return value;\n  }\n\n  getTranslations(locale: string): Record<string, unknown> {\n    return this.translations.get(locale) ?? {};\n  }\n\n  loadTranslations(locale: string, translations: Record<string, unknown>): void {\n    const existing = this.translations.get(locale);\n    if (existing) {\n      // Merge into existing translations\n      this.translations.set(locale, { ...existing, ...translations });\n    } else {\n      this.translations.set(locale, { ...translations });\n    }\n  }\n\n  getLocales(): string[] {\n    return Array.from(this.translations.keys());\n  }\n\n  getDefaultLocale(): string {\n    return this.defaultLocale;\n  }\n\n  setDefaultLocale(locale: string): void {\n    this.defaultLocale = locale;\n  }\n\n  /**\n   * Load all JSON translation files from a directory.\n   * Each file should be named `{locale}.json`.\n   */\n  private loadFromDirectory(dir: string): void {\n    if (!fs.existsSync(dir)) return;\n\n    const files = fs.readdirSync(dir);\n    for (const file of files) {\n      if (!file.endsWith('.json')) continue;\n      const locale = file.replace(/\\.json$/, '');\n      const filePath = path.join(dir, file);\n      try {\n        const content = fs.readFileSync(filePath, 'utf-8');\n        const data = JSON.parse(content) as Record<string, unknown>;\n        this.translations.set(locale, data);\n      } catch {\n        // Skip files that can't be parsed\n      }\n    }\n  }\n\n  private resolveFromLocale(key: string, locale: string): string | undefined {\n    const data = this.translations.get(locale);\n    if (!data) return undefined;\n    return resolveKey(data, key);\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport { FileI18nAdapter } from './file-i18n-adapter.js';\nimport type { FileI18nAdapterOptions } from './file-i18n-adapter.js';\n\n/**\n * Configuration options for the I18nServicePlugin.\n */\nexport interface I18nServicePluginOptions {\n  /** Default locale (default: 'en') */\n  defaultLocale?: string;\n  /** Directory containing locale JSON files */\n  localesDir?: string;\n  /** Fallback locale for missing translations */\n  fallbackLocale?: string;\n}\n\n/**\n * I18nServicePlugin — Production II18nService implementation.\n *\n * Registers an i18n service with the kernel during the init phase.\n * Uses file-based locale loading with JSON files.\n *\n * @example\n * ```ts\n * import { ObjectKernel } from '@objectstack/core';\n * import { I18nServicePlugin } from '@objectstack/service-i18n';\n *\n * const kernel = new ObjectKernel();\n * kernel.use(new I18nServicePlugin({\n *   defaultLocale: 'en',\n *   localesDir: './i18n',\n *   fallbackLocale: 'en',\n * }));\n * await kernel.bootstrap();\n *\n * const i18n = kernel.getService('i18n');\n * i18n.t('objects.account.label', 'en'); // 'Account'\n * ```\n */\nexport class I18nServicePlugin implements Plugin {\n  name = 'com.objectstack.service.i18n';\n  version = '1.0.0';\n  type = 'standard';\n\n  private readonly options: I18nServicePluginOptions;\n\n  constructor(options: I18nServicePluginOptions = {}) {\n    this.options = options;\n  }\n\n  async init(ctx: PluginContext): Promise<void> {\n    const adapterOptions: FileI18nAdapterOptions = {\n      defaultLocale: this.options.defaultLocale,\n      localesDir: this.options.localesDir,\n      fallbackLocale: this.options.fallbackLocale,\n    };\n\n    const i18n = new FileI18nAdapter(adapterOptions);\n    ctx.registerService('i18n', i18n);\n    ctx.logger.info(\n      `I18nServicePlugin: registered file-based i18n adapter (default: ${i18n.getDefaultLocale()})`,\n    );\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/file-i18n-adapter.ts","../src/i18n-service-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport { I18nServicePlugin } from './i18n-service-plugin.js';\nexport type { I18nServicePluginOptions } from './i18n-service-plugin.js';\nexport { FileI18nAdapter } from './file-i18n-adapter.js';\nexport type { FileI18nAdapterOptions } from './file-i18n-adapter.js';\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { II18nService } from '@objectstack/spec/contracts';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\n/**\n * Configuration options for FileI18nAdapter.\n */\nexport interface FileI18nAdapterOptions {\n  /** Default locale (e.g. 'en') */\n  defaultLocale?: string;\n  /** Directory containing locale files (JSON). Each file should be named `{locale}.json`. */\n  localesDir?: string;\n  /** Fallback locale when a key is not found in the requested locale */\n  fallbackLocale?: string;\n}\n\n/**\n * Resolve a nested key in a translations object using dot notation.\n *\n * @param data - Translation data object\n * @param key - Dot-separated key (e.g. 'objects.account.label')\n * @returns The resolved string value, or undefined if not found\n */\nfunction resolveKey(data: Record<string, unknown>, key: string): string | undefined {\n  const parts = key.split('.');\n  let current: unknown = data;\n  for (const part of parts) {\n    if (current == null || typeof current !== 'object') return undefined;\n    current = (current as Record<string, unknown>)[part];\n  }\n  return typeof current === 'string' ? current : undefined;\n}\n\n/**\n * Interpolate parameters into a translated string.\n * Replaces `{{paramName}}` with the corresponding value from params.\n *\n * @param template - Template string with `{{key}}` placeholders\n * @param params - Parameter map\n * @returns Interpolated string\n */\nfunction interpolate(template: string, params: Record<string, unknown>): string {\n  return template.replace(/\\{\\{(\\w+)\\}\\}/g, (_match, key: string) => {\n    return params[key] != null ? String(params[key]) : `{{${key}}}`;\n  });\n}\n\n/**\n * File-based I18n adapter implementing II18nService.\n *\n * Loads JSON translation files from a directory on disk.\n * Each file should be named `{locale}.json` and contain a flat or nested\n * key-value map of translations.\n *\n * Supports:\n * - Dot-notation key resolution (e.g. 'objects.account.label')\n * - Parameter interpolation via `{{paramName}}` syntax\n * - Fallback locale for missing translations\n * - Runtime translation loading via loadTranslations()\n *\n * Suitable for server-side rendering, CLI tools, and development environments.\n *\n * @example\n * ```ts\n * const i18n = new FileI18nAdapter({\n *   defaultLocale: 'en',\n *   localesDir: './i18n',\n *   fallbackLocale: 'en',\n * });\n *\n * i18n.t('objects.account.label', 'zh-CN'); // '客户'\n * i18n.t('greeting', 'en', { name: 'World' }); // 'Hello, World!'\n * ```\n */\nexport class FileI18nAdapter implements II18nService {\n  private readonly translations = new Map<string, Record<string, unknown>>();\n  private defaultLocale: string;\n  private readonly fallbackLocale: string | undefined;\n\n  constructor(options: FileI18nAdapterOptions = {}) {\n    this.defaultLocale = options.defaultLocale ?? 'en';\n    this.fallbackLocale = options.fallbackLocale;\n\n    if (options.localesDir) {\n      this.loadFromDirectory(options.localesDir);\n    }\n  }\n\n  t(key: string, locale: string, params?: Record<string, unknown>): string {\n    // Try requested locale\n    let value = this.resolveFromLocale(key, locale);\n\n    // Try fallback locale\n    if (value === undefined && this.fallbackLocale && this.fallbackLocale !== locale) {\n      value = this.resolveFromLocale(key, this.fallbackLocale);\n    }\n\n    // Return key if not found\n    if (value === undefined) return key;\n\n    // Interpolate parameters\n    if (params && Object.keys(params).length > 0) {\n      return interpolate(value, params);\n    }\n\n    return value;\n  }\n\n  getTranslations(locale: string): Record<string, unknown> {\n    return this.translations.get(locale) ?? {};\n  }\n\n  loadTranslations(locale: string, translations: Record<string, unknown>): void {\n    const existing = this.translations.get(locale);\n    if (existing) {\n      // Merge into existing translations\n      this.translations.set(locale, { ...existing, ...translations });\n    } else {\n      this.translations.set(locale, { ...translations });\n    }\n  }\n\n  getLocales(): string[] {\n    return Array.from(this.translations.keys());\n  }\n\n  getDefaultLocale(): string {\n    return this.defaultLocale;\n  }\n\n  setDefaultLocale(locale: string): void {\n    this.defaultLocale = locale;\n  }\n\n  /**\n   * Load all JSON translation files from a directory.\n   * Each file should be named `{locale}.json`.\n   */\n  private loadFromDirectory(dir: string): void {\n    if (!fs.existsSync(dir)) return;\n\n    const files = fs.readdirSync(dir);\n    for (const file of files) {\n      if (!file.endsWith('.json')) continue;\n      const locale = file.replace(/\\.json$/, '');\n      const filePath = path.join(dir, file);\n      try {\n        const content = fs.readFileSync(filePath, 'utf-8');\n        const data = JSON.parse(content) as Record<string, unknown>;\n        this.translations.set(locale, data);\n      } catch {\n        // Skip files that can't be parsed\n      }\n    }\n  }\n\n  private resolveFromLocale(key: string, locale: string): string | undefined {\n    const data = this.translations.get(locale);\n    if (!data) return undefined;\n    return resolveKey(data, key);\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { IHttpServer, IHttpRequest, IHttpResponse } from '@objectstack/spec/contracts';\nimport type { II18nService } from '@objectstack/spec/contracts';\nimport { FileI18nAdapter } from './file-i18n-adapter.js';\nimport type { FileI18nAdapterOptions } from './file-i18n-adapter.js';\n\n/**\n * Configuration options for the I18nServicePlugin.\n */\nexport interface I18nServicePluginOptions {\n  /** Default locale (default: 'en') */\n  defaultLocale?: string;\n  /** Directory containing locale JSON files */\n  localesDir?: string;\n  /** Fallback locale for missing translations */\n  fallbackLocale?: string;\n  /**\n   * Whether to automatically register i18n REST routes with the HTTP server.\n   * When true (default), the plugin registers `/api/v1/i18n/*` endpoints\n   * via the `kernel:ready` hook. When false or no HTTP server is available,\n   * routes are skipped but the i18n service is still available via the kernel.\n   * @default true\n   */\n  registerRoutes?: boolean;\n  /**\n   * Base path for i18n REST routes.\n   * @default '/api/v1/i18n'\n   */\n  basePath?: string;\n}\n\n/**\n * I18nServicePlugin — Production II18nService implementation.\n *\n * Registers an i18n service with the kernel during the init phase,\n * and self-registers REST endpoints (`/api/v1/i18n/*`) with the HTTP\n * server during the `kernel:ready` hook.\n *\n * REST route self-registration follows the same autonomous plugin pattern\n * used by AuthPlugin, WorkflowPlugin, and other service plugins — RestServer\n * is not involved.\n *\n * @example\n * ```ts\n * import { ObjectKernel } from '@objectstack/core';\n * import { I18nServicePlugin } from '@objectstack/service-i18n';\n *\n * const kernel = new ObjectKernel();\n * kernel.use(new I18nServicePlugin({\n *   defaultLocale: 'en',\n *   localesDir: './i18n',\n *   fallbackLocale: 'en',\n * }));\n * await kernel.bootstrap();\n *\n * const i18n = kernel.getService('i18n');\n * i18n.t('objects.account.label', 'en'); // 'Account'\n * ```\n */\nexport class I18nServicePlugin implements Plugin {\n  name = 'com.objectstack.service.i18n';\n  version = '1.0.0';\n  type = 'standard';\n\n  private readonly options: I18nServicePluginOptions;\n  private i18n: II18nService | null = null;\n\n  constructor(options: I18nServicePluginOptions = {}) {\n    this.options = options;\n  }\n\n  async init(ctx: PluginContext): Promise<void> {\n    const adapterOptions: FileI18nAdapterOptions = {\n      defaultLocale: this.options.defaultLocale,\n      localesDir: this.options.localesDir,\n      fallbackLocale: this.options.fallbackLocale,\n    };\n\n    this.i18n = new FileI18nAdapter(adapterOptions);\n    ctx.registerService('i18n', this.i18n);\n    ctx.logger.info(\n      `I18nServicePlugin: registered file-based i18n adapter (default: ${this.i18n.getDefaultLocale?.() ?? 'en'})`,\n    );\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    // Defer HTTP route registration to kernel:ready hook.\n    // This ensures all plugins (including HonoServerPlugin) have completed\n    // their init and start phases before we attempt to look up the\n    // http-server service — making I18nServicePlugin resilient to plugin\n    // loading order.\n    if (this.options.registerRoutes !== false) {\n      ctx.hook('kernel:ready', async () => {\n        let httpServer: IHttpServer | null = null;\n        try {\n          httpServer = ctx.getService<IHttpServer>('http-server');\n        } catch {\n          // Service not found — expected in MSW/mock mode\n        }\n\n        if (httpServer) {\n          this.registerI18nRoutes(httpServer, ctx);\n        } else {\n          ctx.logger.warn(\n            'No HTTP server available — i18n routes not registered. ' +\n            'i18n service is still available programmatically via kernel.getService(\"i18n\").'\n          );\n        }\n      });\n    }\n  }\n\n  /**\n   * Register i18n REST routes with the HTTP server.\n   *\n   * Routes:\n   * - GET /api/v1/i18n/locales           → list available locales\n   * - GET /api/v1/i18n/translations/:locale → get translations for a locale\n   * - GET /api/v1/i18n/labels/:object/:locale → get field labels for an object\n   */\n  private registerI18nRoutes(httpServer: IHttpServer, ctx: PluginContext): void {\n    if (!this.i18n) return;\n\n    const basePath = this.options.basePath || '/api/v1/i18n';\n    const i18n = this.i18n;\n\n    // GET /i18n/locales\n    httpServer.get(`${basePath}/locales`, async (_req: IHttpRequest, res: IHttpResponse) => {\n      try {\n        const locales = i18n.getLocales();\n        const defaultLocale = i18n.getDefaultLocale?.() ?? 'en';\n        res.json({\n          data: {\n            locales: locales.map((code) => ({\n              code,\n              label: code,\n              isDefault: code === defaultLocale,\n            })),\n          },\n        });\n      } catch (error: any) {\n        res.status(500).json({ error: error.message });\n      }\n    });\n\n    // GET /i18n/translations/:locale\n    httpServer.get(`${basePath}/translations/:locale`, async (req: IHttpRequest, res: IHttpResponse) => {\n      try {\n        const locale = req.params.locale;\n        if (!locale) {\n          res.status(400).json({ error: 'Missing locale parameter' });\n          return;\n        }\n        const translations = i18n.getTranslations(locale);\n        res.json({ data: { locale, translations } });\n      } catch (error: any) {\n        res.status(500).json({ error: error.message });\n      }\n    });\n\n    // GET /i18n/labels/:object/:locale\n    httpServer.get(`${basePath}/labels/:object/:locale`, async (req: IHttpRequest, res: IHttpResponse) => {\n      try {\n        const objectName = req.params.object;\n        const locale = req.params.locale;\n        if (!objectName || !locale) {\n          res.status(400).json({ error: 'Missing object or locale parameter' });\n          return;\n        }\n        // Some implementations may provide a dedicated getFieldLabels method\n        const hasGetFieldLabels = 'getFieldLabels' in i18n\n          && typeof (i18n as Record<string, unknown>)['getFieldLabels'] === 'function';\n        if (hasGetFieldLabels) {\n          const labels = (i18n as II18nService & { getFieldLabels(obj: string, loc: string): Record<string, string> })\n            .getFieldLabels(objectName, locale);\n          res.json({ data: { object: objectName, locale, labels } });\n        } else {\n          // Fallback: derive field labels from full translation bundle\n          const translations = i18n.getTranslations(locale);\n          const prefix = `o.${objectName}.fields.`;\n          const labels: Record<string, string> = {};\n          for (const [key, value] of Object.entries(translations)) {\n            if (key.startsWith(prefix)) {\n              labels[key.substring(prefix.length)] = value as string;\n            }\n          }\n          res.json({ data: { object: objectName, locale, labels } });\n        }\n      } catch (error: any) {\n        res.status(500).json({ error: error.message });\n      }\n    });\n\n    ctx.logger.info(`I18n routes registered: ${basePath}/locales, ${basePath}/translations/:locale, ${basePath}/labels/:object/:locale`);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -11,12 +11,30 @@ interface I18nServicePluginOptions {
     localesDir?: string;
     /** Fallback locale for missing translations */
     fallbackLocale?: string;
+    /**
+     * Whether to automatically register i18n REST routes with the HTTP server.
+     * When true (default), the plugin registers `/api/v1/i18n/*` endpoints
+     * via the `kernel:ready` hook. When false or no HTTP server is available,
+     * routes are skipped but the i18n service is still available via the kernel.
+     * @default true
+     */
+    registerRoutes?: boolean;
+    /**
+     * Base path for i18n REST routes.
+     * @default '/api/v1/i18n'
+     */
+    basePath?: string;
 }
 /**
  * I18nServicePlugin — Production II18nService implementation.
  *
- * Registers an i18n service with the kernel during the init phase.
- * Uses file-based locale loading with JSON files.
+ * Registers an i18n service with the kernel during the init phase,
+ * and self-registers REST endpoints (`/api/v1/i18n/*`) with the HTTP
+ * server during the `kernel:ready` hook.
+ *
+ * REST route self-registration follows the same autonomous plugin pattern
+ * used by AuthPlugin, WorkflowPlugin, and other service plugins — RestServer
+ * is not involved.
  *
  * @example
  * ```ts
@@ -40,8 +58,19 @@ declare class I18nServicePlugin implements Plugin {
     version: string;
     type: string;
     private readonly options;
+    private i18n;
     constructor(options?: I18nServicePluginOptions);
     init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    /**
+     * Register i18n REST routes with the HTTP server.
+     *
+     * Routes:
+     * - GET /api/v1/i18n/locales           → list available locales
+     * - GET /api/v1/i18n/translations/:locale → get translations for a locale
+     * - GET /api/v1/i18n/labels/:object/:locale → get field labels for an object
+     */
+    private registerI18nRoutes;
 }
 
 /**

package/dist/index.d.ts

@@ -11,12 +11,30 @@ interface I18nServicePluginOptions {
     localesDir?: string;
     /** Fallback locale for missing translations */
     fallbackLocale?: string;
+    /**
+     * Whether to automatically register i18n REST routes with the HTTP server.
+     * When true (default), the plugin registers `/api/v1/i18n/*` endpoints
+     * via the `kernel:ready` hook. When false or no HTTP server is available,
+     * routes are skipped but the i18n service is still available via the kernel.
+     * @default true
+     */
+    registerRoutes?: boolean;
+    /**
+     * Base path for i18n REST routes.
+     * @default '/api/v1/i18n'
+     */
+    basePath?: string;
 }
 /**
  * I18nServicePlugin — Production II18nService implementation.
  *
- * Registers an i18n service with the kernel during the init phase.
- * Uses file-based locale loading with JSON files.
+ * Registers an i18n service with the kernel during the init phase,
+ * and self-registers REST endpoints (`/api/v1/i18n/*`) with the HTTP
+ * server during the `kernel:ready` hook.
+ *
+ * REST route self-registration follows the same autonomous plugin pattern
+ * used by AuthPlugin, WorkflowPlugin, and other service plugins — RestServer
+ * is not involved.
  *
  * @example
  * ```ts
@@ -40,8 +58,19 @@ declare class I18nServicePlugin implements Plugin {
     version: string;
     type: string;
     private readonly options;
+    private i18n;
     constructor(options?: I18nServicePluginOptions);
     init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    /**
+     * Register i18n REST routes with the HTTP server.
+     *
+     * Routes:
+     * - GET /api/v1/i18n/locales           → list available locales
+     * - GET /api/v1/i18n/translations/:locale → get translations for a locale
+     * - GET /api/v1/i18n/labels/:object/:locale → get field labels for an object
+     */
+    private registerI18nRoutes;
 }
 
 /**

package/dist/index.js

@@ -87,6 +87,7 @@ var I18nServicePlugin = class {
     this.name = "com.objectstack.service.i18n";
     this.version = "1.0.0";
     this.type = "standard";
+    this.i18n = null;
     this.options = options;
   }
   async init(ctx) {
@@ -95,12 +96,101 @@ var I18nServicePlugin = class {
       localesDir: this.options.localesDir,
       fallbackLocale: this.options.fallbackLocale
     };
-    const i18n = new FileI18nAdapter(adapterOptions);
-    ctx.registerService("i18n", i18n);
+    this.i18n = new FileI18nAdapter(adapterOptions);
+    ctx.registerService("i18n", this.i18n);
     ctx.logger.info(
-      `I18nServicePlugin: registered file-based i18n adapter (default: ${i18n.getDefaultLocale()})`
+      `I18nServicePlugin: registered file-based i18n adapter (default: ${this.i18n.getDefaultLocale?.() ?? "en"})`
     );
   }
+  async start(ctx) {
+    if (this.options.registerRoutes !== false) {
+      ctx.hook("kernel:ready", async () => {
+        let httpServer = null;
+        try {
+          httpServer = ctx.getService("http-server");
+        } catch {
+        }
+        if (httpServer) {
+          this.registerI18nRoutes(httpServer, ctx);
+        } else {
+          ctx.logger.warn(
+            'No HTTP server available \u2014 i18n routes not registered. i18n service is still available programmatically via kernel.getService("i18n").'
+          );
+        }
+      });
+    }
+  }
+  /**
+   * Register i18n REST routes with the HTTP server.
+   *
+   * Routes:
+   * - GET /api/v1/i18n/locales           → list available locales
+   * - GET /api/v1/i18n/translations/:locale → get translations for a locale
+   * - GET /api/v1/i18n/labels/:object/:locale → get field labels for an object
+   */
+  registerI18nRoutes(httpServer, ctx) {
+    if (!this.i18n) return;
+    const basePath = this.options.basePath || "/api/v1/i18n";
+    const i18n = this.i18n;
+    httpServer.get(`${basePath}/locales`, async (_req, res) => {
+      try {
+        const locales = i18n.getLocales();
+        const defaultLocale = i18n.getDefaultLocale?.() ?? "en";
+        res.json({
+          data: {
+            locales: locales.map((code) => ({
+              code,
+              label: code,
+              isDefault: code === defaultLocale
+            }))
+          }
+        });
+      } catch (error) {
+        res.status(500).json({ error: error.message });
+      }
+    });
+    httpServer.get(`${basePath}/translations/:locale`, async (req, res) => {
+      try {
+        const locale = req.params.locale;
+        if (!locale) {
+          res.status(400).json({ error: "Missing locale parameter" });
+          return;
+        }
+        const translations = i18n.getTranslations(locale);
+        res.json({ data: { locale, translations } });
+      } catch (error) {
+        res.status(500).json({ error: error.message });
+      }
+    });
+    httpServer.get(`${basePath}/labels/:object/:locale`, async (req, res) => {
+      try {
+        const objectName = req.params.object;
+        const locale = req.params.locale;
+        if (!objectName || !locale) {
+          res.status(400).json({ error: "Missing object or locale parameter" });
+          return;
+        }
+        const hasGetFieldLabels = "getFieldLabels" in i18n && typeof i18n["getFieldLabels"] === "function";
+        if (hasGetFieldLabels) {
+          const labels = i18n.getFieldLabels(objectName, locale);
+          res.json({ data: { object: objectName, locale, labels } });
+        } else {
+          const translations = i18n.getTranslations(locale);
+          const prefix = `o.${objectName}.fields.`;
+          const labels = {};
+          for (const [key, value] of Object.entries(translations)) {
+            if (key.startsWith(prefix)) {
+              labels[key.substring(prefix.length)] = value;
+            }
+          }
+          res.json({ data: { object: objectName, locale, labels } });
+        }
+      } catch (error) {
+        res.status(500).json({ error: error.message });
+      }
+    });
+    ctx.logger.info(`I18n routes registered: ${basePath}/locales, ${basePath}/translations/:locale, ${basePath}/labels/:object/:locale`);
+  }
 };
 export {
   FileI18nAdapter,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/file-i18n-adapter.ts","../src/i18n-service-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { II18nService } from '@objectstack/spec/contracts';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\n/**\n * Configuration options for FileI18nAdapter.\n */\nexport interface FileI18nAdapterOptions {\n  /** Default locale (e.g. 'en') */\n  defaultLocale?: string;\n  /** Directory containing locale files (JSON). Each file should be named `{locale}.json`. */\n  localesDir?: string;\n  /** Fallback locale when a key is not found in the requested locale */\n  fallbackLocale?: string;\n}\n\n/**\n * Resolve a nested key in a translations object using dot notation.\n *\n * @param data - Translation data object\n * @param key - Dot-separated key (e.g. 'objects.account.label')\n * @returns The resolved string value, or undefined if not found\n */\nfunction resolveKey(data: Record<string, unknown>, key: string): string | undefined {\n  const parts = key.split('.');\n  let current: unknown = data;\n  for (const part of parts) {\n    if (current == null || typeof current !== 'object') return undefined;\n    current = (current as Record<string, unknown>)[part];\n  }\n  return typeof current === 'string' ? current : undefined;\n}\n\n/**\n * Interpolate parameters into a translated string.\n * Replaces `{{paramName}}` with the corresponding value from params.\n *\n * @param template - Template string with `{{key}}` placeholders\n * @param params - Parameter map\n * @returns Interpolated string\n */\nfunction interpolate(template: string, params: Record<string, unknown>): string {\n  return template.replace(/\\{\\{(\\w+)\\}\\}/g, (_match, key: string) => {\n    return params[key] != null ? String(params[key]) : `{{${key}}}`;\n  });\n}\n\n/**\n * File-based I18n adapter implementing II18nService.\n *\n * Loads JSON translation files from a directory on disk.\n * Each file should be named `{locale}.json` and contain a flat or nested\n * key-value map of translations.\n *\n * Supports:\n * - Dot-notation key resolution (e.g. 'objects.account.label')\n * - Parameter interpolation via `{{paramName}}` syntax\n * - Fallback locale for missing translations\n * - Runtime translation loading via loadTranslations()\n *\n * Suitable for server-side rendering, CLI tools, and development environments.\n *\n * @example\n * ```ts\n * const i18n = new FileI18nAdapter({\n *   defaultLocale: 'en',\n *   localesDir: './i18n',\n *   fallbackLocale: 'en',\n * });\n *\n * i18n.t('objects.account.label', 'zh-CN'); // '客户'\n * i18n.t('greeting', 'en', { name: 'World' }); // 'Hello, World!'\n * ```\n */\nexport class FileI18nAdapter implements II18nService {\n  private readonly translations = new Map<string, Record<string, unknown>>();\n  private defaultLocale: string;\n  private readonly fallbackLocale: string | undefined;\n\n  constructor(options: FileI18nAdapterOptions = {}) {\n    this.defaultLocale = options.defaultLocale ?? 'en';\n    this.fallbackLocale = options.fallbackLocale;\n\n    if (options.localesDir) {\n      this.loadFromDirectory(options.localesDir);\n    }\n  }\n\n  t(key: string, locale: string, params?: Record<string, unknown>): string {\n    // Try requested locale\n    let value = this.resolveFromLocale(key, locale);\n\n    // Try fallback locale\n    if (value === undefined && this.fallbackLocale && this.fallbackLocale !== locale) {\n      value = this.resolveFromLocale(key, this.fallbackLocale);\n    }\n\n    // Return key if not found\n    if (value === undefined) return key;\n\n    // Interpolate parameters\n    if (params && Object.keys(params).length > 0) {\n      return interpolate(value, params);\n    }\n\n    return value;\n  }\n\n  getTranslations(locale: string): Record<string, unknown> {\n    return this.translations.get(locale) ?? {};\n  }\n\n  loadTranslations(locale: string, translations: Record<string, unknown>): void {\n    const existing = this.translations.get(locale);\n    if (existing) {\n      // Merge into existing translations\n      this.translations.set(locale, { ...existing, ...translations });\n    } else {\n      this.translations.set(locale, { ...translations });\n    }\n  }\n\n  getLocales(): string[] {\n    return Array.from(this.translations.keys());\n  }\n\n  getDefaultLocale(): string {\n    return this.defaultLocale;\n  }\n\n  setDefaultLocale(locale: string): void {\n    this.defaultLocale = locale;\n  }\n\n  /**\n   * Load all JSON translation files from a directory.\n   * Each file should be named `{locale}.json`.\n   */\n  private loadFromDirectory(dir: string): void {\n    if (!fs.existsSync(dir)) return;\n\n    const files = fs.readdirSync(dir);\n    for (const file of files) {\n      if (!file.endsWith('.json')) continue;\n      const locale = file.replace(/\\.json$/, '');\n      const filePath = path.join(dir, file);\n      try {\n        const content = fs.readFileSync(filePath, 'utf-8');\n        const data = JSON.parse(content) as Record<string, unknown>;\n        this.translations.set(locale, data);\n      } catch {\n        // Skip files that can't be parsed\n      }\n    }\n  }\n\n  private resolveFromLocale(key: string, locale: string): string | undefined {\n    const data = this.translations.get(locale);\n    if (!data) return undefined;\n    return resolveKey(data, key);\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport { FileI18nAdapter } from './file-i18n-adapter.js';\nimport type { FileI18nAdapterOptions } from './file-i18n-adapter.js';\n\n/**\n * Configuration options for the I18nServicePlugin.\n */\nexport interface I18nServicePluginOptions {\n  /** Default locale (default: 'en') */\n  defaultLocale?: string;\n  /** Directory containing locale JSON files */\n  localesDir?: string;\n  /** Fallback locale for missing translations */\n  fallbackLocale?: string;\n}\n\n/**\n * I18nServicePlugin — Production II18nService implementation.\n *\n * Registers an i18n service with the kernel during the init phase.\n * Uses file-based locale loading with JSON files.\n *\n * @example\n * ```ts\n * import { ObjectKernel } from '@objectstack/core';\n * import { I18nServicePlugin } from '@objectstack/service-i18n';\n *\n * const kernel = new ObjectKernel();\n * kernel.use(new I18nServicePlugin({\n *   defaultLocale: 'en',\n *   localesDir: './i18n',\n *   fallbackLocale: 'en',\n * }));\n * await kernel.bootstrap();\n *\n * const i18n = kernel.getService('i18n');\n * i18n.t('objects.account.label', 'en'); // 'Account'\n * ```\n */\nexport class I18nServicePlugin implements Plugin {\n  name = 'com.objectstack.service.i18n';\n  version = '1.0.0';\n  type = 'standard';\n\n  private readonly options: I18nServicePluginOptions;\n\n  constructor(options: I18nServicePluginOptions = {}) {\n    this.options = options;\n  }\n\n  async init(ctx: PluginContext): Promise<void> {\n    const adapterOptions: FileI18nAdapterOptions = {\n      defaultLocale: this.options.defaultLocale,\n      localesDir: this.options.localesDir,\n      fallbackLocale: this.options.fallbackLocale,\n    };\n\n    const i18n = new FileI18nAdapter(adapterOptions);\n    ctx.registerService('i18n', i18n);\n    ctx.logger.info(\n      `I18nServicePlugin: registered file-based i18n adapter (default: ${i18n.getDefaultLocale()})`,\n    );\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/file-i18n-adapter.ts","../src/i18n-service-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { II18nService } from '@objectstack/spec/contracts';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\n/**\n * Configuration options for FileI18nAdapter.\n */\nexport interface FileI18nAdapterOptions {\n  /** Default locale (e.g. 'en') */\n  defaultLocale?: string;\n  /** Directory containing locale files (JSON). Each file should be named `{locale}.json`. */\n  localesDir?: string;\n  /** Fallback locale when a key is not found in the requested locale */\n  fallbackLocale?: string;\n}\n\n/**\n * Resolve a nested key in a translations object using dot notation.\n *\n * @param data - Translation data object\n * @param key - Dot-separated key (e.g. 'objects.account.label')\n * @returns The resolved string value, or undefined if not found\n */\nfunction resolveKey(data: Record<string, unknown>, key: string): string | undefined {\n  const parts = key.split('.');\n  let current: unknown = data;\n  for (const part of parts) {\n    if (current == null || typeof current !== 'object') return undefined;\n    current = (current as Record<string, unknown>)[part];\n  }\n  return typeof current === 'string' ? current : undefined;\n}\n\n/**\n * Interpolate parameters into a translated string.\n * Replaces `{{paramName}}` with the corresponding value from params.\n *\n * @param template - Template string with `{{key}}` placeholders\n * @param params - Parameter map\n * @returns Interpolated string\n */\nfunction interpolate(template: string, params: Record<string, unknown>): string {\n  return template.replace(/\\{\\{(\\w+)\\}\\}/g, (_match, key: string) => {\n    return params[key] != null ? String(params[key]) : `{{${key}}}`;\n  });\n}\n\n/**\n * File-based I18n adapter implementing II18nService.\n *\n * Loads JSON translation files from a directory on disk.\n * Each file should be named `{locale}.json` and contain a flat or nested\n * key-value map of translations.\n *\n * Supports:\n * - Dot-notation key resolution (e.g. 'objects.account.label')\n * - Parameter interpolation via `{{paramName}}` syntax\n * - Fallback locale for missing translations\n * - Runtime translation loading via loadTranslations()\n *\n * Suitable for server-side rendering, CLI tools, and development environments.\n *\n * @example\n * ```ts\n * const i18n = new FileI18nAdapter({\n *   defaultLocale: 'en',\n *   localesDir: './i18n',\n *   fallbackLocale: 'en',\n * });\n *\n * i18n.t('objects.account.label', 'zh-CN'); // '客户'\n * i18n.t('greeting', 'en', { name: 'World' }); // 'Hello, World!'\n * ```\n */\nexport class FileI18nAdapter implements II18nService {\n  private readonly translations = new Map<string, Record<string, unknown>>();\n  private defaultLocale: string;\n  private readonly fallbackLocale: string | undefined;\n\n  constructor(options: FileI18nAdapterOptions = {}) {\n    this.defaultLocale = options.defaultLocale ?? 'en';\n    this.fallbackLocale = options.fallbackLocale;\n\n    if (options.localesDir) {\n      this.loadFromDirectory(options.localesDir);\n    }\n  }\n\n  t(key: string, locale: string, params?: Record<string, unknown>): string {\n    // Try requested locale\n    let value = this.resolveFromLocale(key, locale);\n\n    // Try fallback locale\n    if (value === undefined && this.fallbackLocale && this.fallbackLocale !== locale) {\n      value = this.resolveFromLocale(key, this.fallbackLocale);\n    }\n\n    // Return key if not found\n    if (value === undefined) return key;\n\n    // Interpolate parameters\n    if (params && Object.keys(params).length > 0) {\n      return interpolate(value, params);\n    }\n\n    return value;\n  }\n\n  getTranslations(locale: string): Record<string, unknown> {\n    return this.translations.get(locale) ?? {};\n  }\n\n  loadTranslations(locale: string, translations: Record<string, unknown>): void {\n    const existing = this.translations.get(locale);\n    if (existing) {\n      // Merge into existing translations\n      this.translations.set(locale, { ...existing, ...translations });\n    } else {\n      this.translations.set(locale, { ...translations });\n    }\n  }\n\n  getLocales(): string[] {\n    return Array.from(this.translations.keys());\n  }\n\n  getDefaultLocale(): string {\n    return this.defaultLocale;\n  }\n\n  setDefaultLocale(locale: string): void {\n    this.defaultLocale = locale;\n  }\n\n  /**\n   * Load all JSON translation files from a directory.\n   * Each file should be named `{locale}.json`.\n   */\n  private loadFromDirectory(dir: string): void {\n    if (!fs.existsSync(dir)) return;\n\n    const files = fs.readdirSync(dir);\n    for (const file of files) {\n      if (!file.endsWith('.json')) continue;\n      const locale = file.replace(/\\.json$/, '');\n      const filePath = path.join(dir, file);\n      try {\n        const content = fs.readFileSync(filePath, 'utf-8');\n        const data = JSON.parse(content) as Record<string, unknown>;\n        this.translations.set(locale, data);\n      } catch {\n        // Skip files that can't be parsed\n      }\n    }\n  }\n\n  private resolveFromLocale(key: string, locale: string): string | undefined {\n    const data = this.translations.get(locale);\n    if (!data) return undefined;\n    return resolveKey(data, key);\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { IHttpServer, IHttpRequest, IHttpResponse } from '@objectstack/spec/contracts';\nimport type { II18nService } from '@objectstack/spec/contracts';\nimport { FileI18nAdapter } from './file-i18n-adapter.js';\nimport type { FileI18nAdapterOptions } from './file-i18n-adapter.js';\n\n/**\n * Configuration options for the I18nServicePlugin.\n */\nexport interface I18nServicePluginOptions {\n  /** Default locale (default: 'en') */\n  defaultLocale?: string;\n  /** Directory containing locale JSON files */\n  localesDir?: string;\n  /** Fallback locale for missing translations */\n  fallbackLocale?: string;\n  /**\n   * Whether to automatically register i18n REST routes with the HTTP server.\n   * When true (default), the plugin registers `/api/v1/i18n/*` endpoints\n   * via the `kernel:ready` hook. When false or no HTTP server is available,\n   * routes are skipped but the i18n service is still available via the kernel.\n   * @default true\n   */\n  registerRoutes?: boolean;\n  /**\n   * Base path for i18n REST routes.\n   * @default '/api/v1/i18n'\n   */\n  basePath?: string;\n}\n\n/**\n * I18nServicePlugin — Production II18nService implementation.\n *\n * Registers an i18n service with the kernel during the init phase,\n * and self-registers REST endpoints (`/api/v1/i18n/*`) with the HTTP\n * server during the `kernel:ready` hook.\n *\n * REST route self-registration follows the same autonomous plugin pattern\n * used by AuthPlugin, WorkflowPlugin, and other service plugins — RestServer\n * is not involved.\n *\n * @example\n * ```ts\n * import { ObjectKernel } from '@objectstack/core';\n * import { I18nServicePlugin } from '@objectstack/service-i18n';\n *\n * const kernel = new ObjectKernel();\n * kernel.use(new I18nServicePlugin({\n *   defaultLocale: 'en',\n *   localesDir: './i18n',\n *   fallbackLocale: 'en',\n * }));\n * await kernel.bootstrap();\n *\n * const i18n = kernel.getService('i18n');\n * i18n.t('objects.account.label', 'en'); // 'Account'\n * ```\n */\nexport class I18nServicePlugin implements Plugin {\n  name = 'com.objectstack.service.i18n';\n  version = '1.0.0';\n  type = 'standard';\n\n  private readonly options: I18nServicePluginOptions;\n  private i18n: II18nService | null = null;\n\n  constructor(options: I18nServicePluginOptions = {}) {\n    this.options = options;\n  }\n\n  async init(ctx: PluginContext): Promise<void> {\n    const adapterOptions: FileI18nAdapterOptions = {\n      defaultLocale: this.options.defaultLocale,\n      localesDir: this.options.localesDir,\n      fallbackLocale: this.options.fallbackLocale,\n    };\n\n    this.i18n = new FileI18nAdapter(adapterOptions);\n    ctx.registerService('i18n', this.i18n);\n    ctx.logger.info(\n      `I18nServicePlugin: registered file-based i18n adapter (default: ${this.i18n.getDefaultLocale?.() ?? 'en'})`,\n    );\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    // Defer HTTP route registration to kernel:ready hook.\n    // This ensures all plugins (including HonoServerPlugin) have completed\n    // their init and start phases before we attempt to look up the\n    // http-server service — making I18nServicePlugin resilient to plugin\n    // loading order.\n    if (this.options.registerRoutes !== false) {\n      ctx.hook('kernel:ready', async () => {\n        let httpServer: IHttpServer | null = null;\n        try {\n          httpServer = ctx.getService<IHttpServer>('http-server');\n        } catch {\n          // Service not found — expected in MSW/mock mode\n        }\n\n        if (httpServer) {\n          this.registerI18nRoutes(httpServer, ctx);\n        } else {\n          ctx.logger.warn(\n            'No HTTP server available — i18n routes not registered. ' +\n            'i18n service is still available programmatically via kernel.getService(\"i18n\").'\n          );\n        }\n      });\n    }\n  }\n\n  /**\n   * Register i18n REST routes with the HTTP server.\n   *\n   * Routes:\n   * - GET /api/v1/i18n/locales           → list available locales\n   * - GET /api/v1/i18n/translations/:locale → get translations for a locale\n   * - GET /api/v1/i18n/labels/:object/:locale → get field labels for an object\n   */\n  private registerI18nRoutes(httpServer: IHttpServer, ctx: PluginContext): void {\n    if (!this.i18n) return;\n\n    const basePath = this.options.basePath || '/api/v1/i18n';\n    const i18n = this.i18n;\n\n    // GET /i18n/locales\n    httpServer.get(`${basePath}/locales`, async (_req: IHttpRequest, res: IHttpResponse) => {\n      try {\n        const locales = i18n.getLocales();\n        const defaultLocale = i18n.getDefaultLocale?.() ?? 'en';\n        res.json({\n          data: {\n            locales: locales.map((code) => ({\n              code,\n              label: code,\n              isDefault: code === defaultLocale,\n            })),\n          },\n        });\n      } catch (error: any) {\n        res.status(500).json({ error: error.message });\n      }\n    });\n\n    // GET /i18n/translations/:locale\n    httpServer.get(`${basePath}/translations/:locale`, async (req: IHttpRequest, res: IHttpResponse) => {\n      try {\n        const locale = req.params.locale;\n        if (!locale) {\n          res.status(400).json({ error: 'Missing locale parameter' });\n          return;\n        }\n        const translations = i18n.getTranslations(locale);\n        res.json({ data: { locale, translations } });\n      } catch (error: any) {\n        res.status(500).json({ error: error.message });\n      }\n    });\n\n    // GET /i18n/labels/:object/:locale\n    httpServer.get(`${basePath}/labels/:object/:locale`, async (req: IHttpRequest, res: IHttpResponse) => {\n      try {\n        const objectName = req.params.object;\n        const locale = req.params.locale;\n        if (!objectName || !locale) {\n          res.status(400).json({ error: 'Missing object or locale parameter' });\n          return;\n        }\n        // Some implementations may provide a dedicated getFieldLabels method\n        const hasGetFieldLabels = 'getFieldLabels' in i18n\n          && typeof (i18n as Record<string, unknown>)['getFieldLabels'] === 'function';\n        if (hasGetFieldLabels) {\n          const labels = (i18n as II18nService & { getFieldLabels(obj: string, loc: string): Record<string, string> })\n            .getFieldLabels(objectName, locale);\n          res.json({ data: { object: objectName, locale, labels } });\n        } else {\n          // Fallback: derive field labels from full translation bundle\n          const translations = i18n.getTranslations(locale);\n          const prefix = `o.${objectName}.fields.`;\n          const labels: Record<string, string> = {};\n          for (const [key, value] of Object.entries(translations)) {\n            if (key.startsWith(prefix)) {\n              labels[key.substring(prefix.length)] = value as string;\n            }\n          }\n          res.json({ data: { object: objectName, locale, labels } });\n        }\n      } catch (error: any) {\n        res.status(500).json({ error: error.message });\n      }\n    });\n\n    ctx.logger.info(`I18n routes registered: ${basePath}/locales, ${basePath}/translations/:locale, ${basePath}/labels/:object/:locale`);\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/service-i18n",
-  "version": "3.2.5",
+  "version": "3.2.7",
   "license": "Apache-2.0",
   "description": "I18n Service for ObjectStack — implements II18nService with file-based locale loading",
   "type": "module",
@@ -9,13 +9,13 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "dependencies": {
-    "@objectstack/core": "3.2.5",
-    "@objectstack/spec": "3.2.5"
+    "@objectstack/core": "3.2.7",
+    "@objectstack/spec": "3.2.7"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/src/i18n-service-plugin.test.ts

@@ -0,0 +1,280 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { I18nServicePlugin } from './i18n-service-plugin';
+import type { IHttpRequest, IHttpResponse, RouteHandler } from '@objectstack/spec/contracts';
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+function createMockHttpServer() {
+  const routes = new Map<string, RouteHandler>();
+  return {
+    get: vi.fn((path: string, handler: RouteHandler) => { routes.set(`GET:${path}`, handler); }),
+    post: vi.fn(),
+    put: vi.fn(),
+    delete: vi.fn(),
+    patch: vi.fn(),
+    use: vi.fn(),
+    listen: vi.fn().mockResolvedValue(undefined),
+    close: vi.fn().mockResolvedValue(undefined),
+    /** Test helper: retrieve a registered handler */
+    _getHandler(method: string, path: string): RouteHandler | undefined {
+      return routes.get(`${method}:${path}`);
+    },
+  };
+}
+
+function createMockPluginContext(services: Record<string, any> = {}) {
+  const hooks = new Map<string, Array<(...args: any[]) => Promise<void>>>();
+  return {
+    registerService: vi.fn(),
+    getService: vi.fn((name: string) => {
+      if (services[name]) return services[name];
+      throw new Error(`Service '${name}' not found`);
+    }),
+    getServices: vi.fn(() => new Map(Object.entries(services))),
+    hook: vi.fn((name: string, handler: (...args: any[]) => Promise<void>) => {
+      if (!hooks.has(name)) hooks.set(name, []);
+      hooks.get(name)!.push(handler);
+    }),
+    trigger: vi.fn(async (name: string, ...args: any[]) => {
+      const handlers = hooks.get(name) ?? [];
+      for (const h of handlers) await h(...args);
+    }),
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    },
+    getKernel: vi.fn(),
+    replaceService: vi.fn(),
+  };
+}
+
+function createMockReq(overrides: Partial<IHttpRequest> = {}): IHttpRequest {
+  return {
+    params: {},
+    query: {},
+    headers: {},
+    method: 'GET',
+    path: '/',
+    ...overrides,
+  };
+}
+
+function createMockRes(): IHttpResponse & { _data: any; _status: number } {
+  const res: any = {
+    _data: null,
+    _status: 200,
+    json(data: any) { res._data = data; },
+    send(data: string) { res._data = data; },
+    status(code: number) { res._status = code; return res; },
+    header() { return res; },
+  };
+  return res;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('I18nServicePlugin', () => {
+  let httpServer: ReturnType<typeof createMockHttpServer>;
+  let ctx: ReturnType<typeof createMockPluginContext>;
+
+  beforeEach(() => {
+    httpServer = createMockHttpServer();
+    ctx = createMockPluginContext({ 'http-server': httpServer });
+  });
+
+  // -- Service registration -------------------------------------------------
+
+  describe('init', () => {
+    it('should register i18n service during init', async () => {
+      const plugin = new I18nServicePlugin();
+      await plugin.init!(ctx as any);
+
+      expect(ctx.registerService).toHaveBeenCalledWith('i18n', expect.any(Object));
+    });
+
+    it('should pass options to the FileI18nAdapter', async () => {
+      const plugin = new I18nServicePlugin({ defaultLocale: 'zh-CN' });
+      await plugin.init!(ctx as any);
+
+      const registeredService = ctx.registerService.mock.calls[0][1];
+      expect(registeredService.getDefaultLocale()).toBe('zh-CN');
+    });
+  });
+
+  // -- Route self-registration ----------------------------------------------
+
+  describe('route self-registration', () => {
+    it('should register a kernel:ready hook during start', async () => {
+      const plugin = new I18nServicePlugin();
+      await plugin.init!(ctx as any);
+      await plugin.start!(ctx as any);
+
+      expect(ctx.hook).toHaveBeenCalledWith('kernel:ready', expect.any(Function));
+    });
+
+    it('should register i18n routes when http-server is available', async () => {
+      const plugin = new I18nServicePlugin();
+      await plugin.init!(ctx as any);
+      await plugin.start!(ctx as any);
+
+      // Simulate kernel:ready
+      await ctx.trigger('kernel:ready');
+
+      expect(httpServer.get).toHaveBeenCalledWith('/api/v1/i18n/locales', expect.any(Function));
+      expect(httpServer.get).toHaveBeenCalledWith('/api/v1/i18n/translations/:locale', expect.any(Function));
+      expect(httpServer.get).toHaveBeenCalledWith('/api/v1/i18n/labels/:object/:locale', expect.any(Function));
+    });
+
+    it('should respect custom basePath', async () => {
+      const plugin = new I18nServicePlugin({ basePath: '/custom/i18n' });
+      await plugin.init!(ctx as any);
+      await plugin.start!(ctx as any);
+
+      await ctx.trigger('kernel:ready');
+
+      expect(httpServer.get).toHaveBeenCalledWith('/custom/i18n/locales', expect.any(Function));
+      expect(httpServer.get).toHaveBeenCalledWith('/custom/i18n/translations/:locale', expect.any(Function));
+      expect(httpServer.get).toHaveBeenCalledWith('/custom/i18n/labels/:object/:locale', expect.any(Function));
+    });
+
+    it('should skip route registration when registerRoutes is false', async () => {
+      const plugin = new I18nServicePlugin({ registerRoutes: false });
+      await plugin.init!(ctx as any);
+      await plugin.start!(ctx as any);
+
+      expect(ctx.hook).not.toHaveBeenCalled();
+    });
+
+    it('should gracefully skip routes when http-server is not available', async () => {
+      const ctxNoHttp = createMockPluginContext({}); // no http-server
+      const plugin = new I18nServicePlugin();
+      await plugin.init!(ctxNoHttp as any);
+      await plugin.start!(ctxNoHttp as any);
+
+      await ctxNoHttp.trigger('kernel:ready');
+
+      expect(ctxNoHttp.logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('No HTTP server available'),
+      );
+    });
+  });
+
+  // -- Route handler behavior -----------------------------------------------
+
+  describe('route handlers', () => {
+    async function setupPlugin(options: ConstructorParameters<typeof I18nServicePlugin>[0] = {}) {
+      const plugin = new I18nServicePlugin(options);
+      await plugin.init!(ctx as any);
+      // Load some translations after init so the service has data
+      const i18n = ctx.registerService.mock.calls[0][1];
+      i18n.loadTranslations('en', { greeting: 'Hello', 'o.account.fields.name': 'Account Name' });
+      i18n.loadTranslations('zh-CN', { greeting: '你好', 'o.account.fields.name': '账户名称' });
+      await plugin.start!(ctx as any);
+      await ctx.trigger('kernel:ready');
+      return { plugin, i18n };
+    }
+
+    it('GET /locales should return all available locales', async () => {
+      await setupPlugin();
+
+      const handler = httpServer._getHandler('GET', '/api/v1/i18n/locales')!;
+      expect(handler).toBeDefined();
+
+      const req = createMockReq();
+      const res = createMockRes();
+      await handler(req, res);
+
+      expect(res._data).toEqual({
+        data: {
+          locales: [
+            { code: 'en', label: 'en', isDefault: true },
+            { code: 'zh-CN', label: 'zh-CN', isDefault: false },
+          ],
+        },
+      });
+    });
+
+    it('GET /translations/:locale should return translations for the given locale', async () => {
+      await setupPlugin();
+
+      const handler = httpServer._getHandler('GET', '/api/v1/i18n/translations/:locale')!;
+      expect(handler).toBeDefined();
+
+      const req = createMockReq({ params: { locale: 'en' } });
+      const res = createMockRes();
+      await handler(req, res);
+
+      expect(res._data).toEqual({
+        data: {
+          locale: 'en',
+          translations: { greeting: 'Hello', 'o.account.fields.name': 'Account Name' },
+        },
+      });
+    });
+
+    it('GET /translations/:locale should return 400 when locale is missing', async () => {
+      await setupPlugin();
+
+      const handler = httpServer._getHandler('GET', '/api/v1/i18n/translations/:locale')!;
+      const req = createMockReq({ params: {} });
+      const res = createMockRes();
+      await handler(req, res);
+
+      expect(res._status).toBe(400);
+      expect(res._data).toEqual({ error: 'Missing locale parameter' });
+    });
+
+    it('GET /labels/:object/:locale should derive field labels from translation bundle', async () => {
+      await setupPlugin();
+
+      const handler = httpServer._getHandler('GET', '/api/v1/i18n/labels/:object/:locale')!;
+      expect(handler).toBeDefined();
+
+      const req = createMockReq({ params: { object: 'account', locale: 'en' } });
+      const res = createMockRes();
+      await handler(req, res);
+
+      expect(res._data).toEqual({
+        data: {
+          object: 'account',
+          locale: 'en',
+          labels: { name: 'Account Name' },
+        },
+      });
+    });
+
+    it('GET /labels/:object/:locale should return 400 when params are missing', async () => {
+      await setupPlugin();
+
+      const handler = httpServer._getHandler('GET', '/api/v1/i18n/labels/:object/:locale')!;
+      const req = createMockReq({ params: {} });
+      const res = createMockRes();
+      await handler(req, res);
+
+      expect(res._status).toBe(400);
+      expect(res._data).toEqual({ error: 'Missing object or locale parameter' });
+    });
+  });
+
+  // -- Plugin metadata -------------------------------------------------------
+
+  describe('plugin metadata', () => {
+    it('should have correct plugin name', () => {
+      const plugin = new I18nServicePlugin();
+      expect(plugin.name).toBe('com.objectstack.service.i18n');
+    });
+
+    it('should have version', () => {
+      const plugin = new I18nServicePlugin();
+      expect(plugin.version).toBe('1.0.0');
+    });
+  });
+});

package/src/i18n-service-plugin.ts

@@ -1,6 +1,8 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type { Plugin, PluginContext } from '@objectstack/core';
+import type { IHttpServer, IHttpRequest, IHttpResponse } from '@objectstack/spec/contracts';
+import type { II18nService } from '@objectstack/spec/contracts';
 import { FileI18nAdapter } from './file-i18n-adapter.js';
 import type { FileI18nAdapterOptions } from './file-i18n-adapter.js';
 
@@ -14,13 +16,31 @@ export interface I18nServicePluginOptions {
   localesDir?: string;
   /** Fallback locale for missing translations */
   fallbackLocale?: string;
+  /**
+   * Whether to automatically register i18n REST routes with the HTTP server.
+   * When true (default), the plugin registers `/api/v1/i18n/*` endpoints
+   * via the `kernel:ready` hook. When false or no HTTP server is available,
+   * routes are skipped but the i18n service is still available via the kernel.
+   * @default true
+   */
+  registerRoutes?: boolean;
+  /**
+   * Base path for i18n REST routes.
+   * @default '/api/v1/i18n'
+   */
+  basePath?: string;
 }
 
 /**
  * I18nServicePlugin — Production II18nService implementation.
  *
- * Registers an i18n service with the kernel during the init phase.
- * Uses file-based locale loading with JSON files.
+ * Registers an i18n service with the kernel during the init phase,
+ * and self-registers REST endpoints (`/api/v1/i18n/*`) with the HTTP
+ * server during the `kernel:ready` hook.
+ *
+ * REST route self-registration follows the same autonomous plugin pattern
+ * used by AuthPlugin, WorkflowPlugin, and other service plugins — RestServer
+ * is not involved.
  *
  * @example
  * ```ts
@@ -45,6 +65,7 @@ export class I18nServicePlugin implements Plugin {
   type = 'standard';
 
   private readonly options: I18nServicePluginOptions;
+  private i18n: II18nService | null = null;
 
   constructor(options: I18nServicePluginOptions = {}) {
     this.options = options;
@@ -57,10 +78,121 @@ export class I18nServicePlugin implements Plugin {
       fallbackLocale: this.options.fallbackLocale,
     };
 
-    const i18n = new FileI18nAdapter(adapterOptions);
-    ctx.registerService('i18n', i18n);
+    this.i18n = new FileI18nAdapter(adapterOptions);
+    ctx.registerService('i18n', this.i18n);
     ctx.logger.info(
-      `I18nServicePlugin: registered file-based i18n adapter (default: ${i18n.getDefaultLocale()})`,
+      `I18nServicePlugin: registered file-based i18n adapter (default: ${this.i18n.getDefaultLocale?.() ?? 'en'})`,
     );
   }
+
+  async start(ctx: PluginContext): Promise<void> {
+    // Defer HTTP route registration to kernel:ready hook.
+    // This ensures all plugins (including HonoServerPlugin) have completed
+    // their init and start phases before we attempt to look up the
+    // http-server service — making I18nServicePlugin resilient to plugin
+    // loading order.
+    if (this.options.registerRoutes !== false) {
+      ctx.hook('kernel:ready', async () => {
+        let httpServer: IHttpServer | null = null;
+        try {
+          httpServer = ctx.getService<IHttpServer>('http-server');
+        } catch {
+          // Service not found — expected in MSW/mock mode
+        }
+
+        if (httpServer) {
+          this.registerI18nRoutes(httpServer, ctx);
+        } else {
+          ctx.logger.warn(
+            'No HTTP server available — i18n routes not registered. ' +
+            'i18n service is still available programmatically via kernel.getService("i18n").'
+          );
+        }
+      });
+    }
+  }
+
+  /**
+   * Register i18n REST routes with the HTTP server.
+   *
+   * Routes:
+   * - GET /api/v1/i18n/locales           → list available locales
+   * - GET /api/v1/i18n/translations/:locale → get translations for a locale
+   * - GET /api/v1/i18n/labels/:object/:locale → get field labels for an object
+   */
+  private registerI18nRoutes(httpServer: IHttpServer, ctx: PluginContext): void {
+    if (!this.i18n) return;
+
+    const basePath = this.options.basePath || '/api/v1/i18n';
+    const i18n = this.i18n;
+
+    // GET /i18n/locales
+    httpServer.get(`${basePath}/locales`, async (_req: IHttpRequest, res: IHttpResponse) => {
+      try {
+        const locales = i18n.getLocales();
+        const defaultLocale = i18n.getDefaultLocale?.() ?? 'en';
+        res.json({
+          data: {
+            locales: locales.map((code) => ({
+              code,
+              label: code,
+              isDefault: code === defaultLocale,
+            })),
+          },
+        });
+      } catch (error: any) {
+        res.status(500).json({ error: error.message });
+      }
+    });
+
+    // GET /i18n/translations/:locale
+    httpServer.get(`${basePath}/translations/:locale`, async (req: IHttpRequest, res: IHttpResponse) => {
+      try {
+        const locale = req.params.locale;
+        if (!locale) {
+          res.status(400).json({ error: 'Missing locale parameter' });
+          return;
+        }
+        const translations = i18n.getTranslations(locale);
+        res.json({ data: { locale, translations } });
+      } catch (error: any) {
+        res.status(500).json({ error: error.message });
+      }
+    });
+
+    // GET /i18n/labels/:object/:locale
+    httpServer.get(`${basePath}/labels/:object/:locale`, async (req: IHttpRequest, res: IHttpResponse) => {
+      try {
+        const objectName = req.params.object;
+        const locale = req.params.locale;
+        if (!objectName || !locale) {
+          res.status(400).json({ error: 'Missing object or locale parameter' });
+          return;
+        }
+        // Some implementations may provide a dedicated getFieldLabels method
+        const hasGetFieldLabels = 'getFieldLabels' in i18n
+          && typeof (i18n as Record<string, unknown>)['getFieldLabels'] === 'function';
+        if (hasGetFieldLabels) {
+          const labels = (i18n as II18nService & { getFieldLabels(obj: string, loc: string): Record<string, string> })
+            .getFieldLabels(objectName, locale);
+          res.json({ data: { object: objectName, locale, labels } });
+        } else {
+          // Fallback: derive field labels from full translation bundle
+          const translations = i18n.getTranslations(locale);
+          const prefix = `o.${objectName}.fields.`;
+          const labels: Record<string, string> = {};
+          for (const [key, value] of Object.entries(translations)) {
+            if (key.startsWith(prefix)) {
+              labels[key.substring(prefix.length)] = value as string;
+            }
+          }
+          res.json({ data: { object: objectName, locale, labels } });
+        }
+      } catch (error: any) {
+        res.status(500).json({ error: error.message });
+      }
+    });
+
+    ctx.logger.info(`I18n routes registered: ${basePath}/locales, ${basePath}/translations/:locale, ${basePath}/labels/:object/:locale`);
+  }
 }