feat: AppPlugin i18n auto-loading, enhanced tests, and documentation

Copilot · hotlong · Copilot · commit 31ce8e9b6469 · 2026-03-11T04:04:12.000Z
- AppPlugin.start() auto-loads translation bundles into i18n service
- Added 10 new tests: AppPlugin i18n loading + environment consistency
- Added i18n service registration guide to kernel-services.mdx
- Updated CHANGELOG.md with Added section

Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated all framework adapters (Hono, Express, Fastify, Next.js, NestJS, Nuxt, SvelteKit),
   the dispatcher plugin, and the MSW plugin to `await` the now-async `getDiscoveryInfo()`.
 
+### Added
+- **AppPlugin i18n auto-loading** — `AppPlugin` now automatically loads translation bundles from
+  app configs (`translations` array) into the kernel's i18n service during the `start` phase,
+  coordinating i18n data loading across server/dev/mock environments.
+- i18n service registration guide in `content/docs/guides/kernel-services.mdx` documenting
+  service registration patterns, discovery consistency, and AppPlugin auto-loading behavior.
+
 ### Changed
 - Updated ROADMAP.md for v3.0 release preparation with full codebase scan results
 - Audited all @deprecated items: 14 in spec, 9 in runtime packages (23 total)
diff --git a/content/docs/guides/kernel-services.mdx b/content/docs/guides/kernel-services.mdx
@@ -246,6 +246,68 @@ Trigger engine, event triggers from ObjectQL hooks, flow executor, scheduled tri
 ### 11. i18n — 3 methods
 `getLocales`, `getTranslations`, `getFieldLabels`
 
+**Service Name**: `i18n` · **Criticality**: `optional`  
+**Implementations**: `@objectstack/service-i18n` (production — file-based) · Dev Plugin (in-memory stub)  
+**Route Mount**: `/api/v1/i18n`  
+**Contract**: `II18nService` in `@objectstack/spec/contracts`
+
+#### Service Registration
+
+The i18n service is registered by a **plugin** during the `init` phase:
+
+| Environment | Provider | Registration |
+|:------------|:---------|:-------------|
+| **Production** | `I18nServicePlugin` | File-based `FileI18nAdapter` loads JSON locale files from disk |
+| **Development** | `DevPlugin` | In-memory Map-backed stub, supports `loadTranslations()` |
+| **Mock / MSW** | `MswPlugin` | Routes via `HttpDispatcher.dispatch()` catch-all — requires one of the above |
+
+```typescript
+// Production
+kernel.use(new I18nServicePlugin({ defaultLocale: 'en', localesDir: './i18n' }));
+
+// Development (automatic — DevPlugin registers i18n stub for all 17 core services)
+kernel.use(new DevPlugin());
+```
+
+#### Discovery & Handler Consistency
+
+The Discovery API (`/api/v1` or `/.well-known/objectstack`) and the i18n route handler (`/api/v1/i18n/*`) both use the **same async resolution chain** to detect i18n availability:
+
+```
+getServiceAsync() → getService() → context.getService() → services Map
+```
+
+This ensures that `discovery.services.i18n.status` always matches the actual runtime behavior — a service registered via any mechanism (sync Map, async factory, or context) will be reported correctly in both places.
+
+The `locale` field in the discovery response is populated from the actual i18n service:
+- `locale.default` — from `i18nService.getDefaultLocale()` (falls back to `'en'`)
+- `locale.supported` — from `i18nService.getLocales()` (falls back to `[default]`)
+
+#### AppPlugin Auto-Loading
+
+When an app bundle includes an `i18n` config and `translations` array, `AppPlugin` automatically loads the translation data into the i18n service during the `start` phase:
+
+```typescript
+export default defineStack({
+  manifest: { id: 'com.example.crm', namespace: 'crm' },
+  i18n: { defaultLocale: 'en', supportedLocales: ['en', 'zh-CN'] },
+  translations: [CrmTranslations],   // TranslationBundle[]
+});
+```
+
+AppPlugin will:
+1. Set the default locale via `i18nService.setDefaultLocale()`
+2. Call `i18nService.loadTranslations(locale, data)` for each locale in every bundle
+3. Skip gracefully if no i18n service is registered (no errors, just a debug log)
+
+#### REST API Endpoints
+
+| Method | Path | Description |
+|:-------|:-----|:------------|
+| `GET` | `/api/v1/i18n/locales` | List available locales |
+| `GET` | `/api/v1/i18n/translations/:locale` | Get all translations for a locale |
+| `GET` | `/api/v1/i18n/labels/:object/:locale` | Get translated field labels for an object |
+
 ---
 
 ## 12–17. Infrastructure Services ❌ Plugin Required
diff --git a/packages/runtime/src/app-plugin.test.ts b/packages/runtime/src/app-plugin.test.ts
@@ -99,4 +99,115 @@ describe('AppPlugin', () => {
             expect.any(Object)
         );
     });
+
+    // ═══════════════════════════════════════════════════════════════
+    // i18n translation auto-loading
+    // ═══════════════════════════════════════════════════════════════
+
+    describe('i18n translation loading', () => {
+        let mockI18n: any;
+        let mockQL: any;
+
+        beforeEach(() => {
+            mockI18n = {
+                loadTranslations: vi.fn(),
+                setDefaultLocale: vi.fn(),
+                getLocales: vi.fn().mockReturnValue([]),
+                getDefaultLocale: vi.fn().mockReturnValue('en'),
+            };
+            mockQL = { registry: {} };
+
+            vi.mocked(mockContext.getService).mockImplementation((name: string) => {
+                if (name === 'objectql') return mockQL;
+                if (name === 'i18n') return mockI18n;
+                return undefined;
+            });
+        });
+
+        it('should auto-load translations from bundle into i18n service', async () => {
+            const bundle = {
+                id: 'com.test.i18n',
+                translations: [
+                    {
+                        en: { objects: { task: { label: 'Task' } } },
+                        'zh-CN': { objects: { task: { label: '任务' } } },
+                    },
+                ],
+            };
+            const plugin = new AppPlugin(bundle);
+            await plugin.start!(mockContext);
+
+            expect(mockI18n.loadTranslations).toHaveBeenCalledWith('en', { objects: { task: { label: 'Task' } } });
+            expect(mockI18n.loadTranslations).toHaveBeenCalledWith('zh-CN', { objects: { task: { label: '任务' } } });
+        });
+
+        it('should set default locale from i18n config', async () => {
+            const bundle = {
+                id: 'com.test.locale',
+                i18n: { defaultLocale: 'zh-CN', supportedLocales: ['en', 'zh-CN'] },
+                translations: [{ en: { messages: { hello: 'Hello' } } }],
+            };
+            const plugin = new AppPlugin(bundle);
+            await plugin.start!(mockContext);
+
+            expect(mockI18n.setDefaultLocale).toHaveBeenCalledWith('zh-CN');
+        });
+
+        it('should skip translation loading when i18n service is not registered', async () => {
+            vi.mocked(mockContext.getService).mockImplementation((name: string) => {
+                if (name === 'objectql') return mockQL;
+                return undefined; // No i18n service
+            });
+
+            const bundle = {
+                id: 'com.test.noi18n',
+                translations: [{ en: { messages: { hello: 'Hello' } } }],
+            };
+            const plugin = new AppPlugin(bundle);
+            await plugin.start!(mockContext);
+
+            // Should log debug but not throw
+            expect(mockContext.logger.debug).toHaveBeenCalledWith(
+                expect.stringContaining('No i18n service registered'),
+                expect.any(Object)
+            );
+        });
+
+        it('should handle bundle with no translations gracefully', async () => {
+            const bundle = { id: 'com.test.notrans' };
+            const plugin = new AppPlugin(bundle);
+            await plugin.start!(mockContext);
+
+            expect(mockI18n.loadTranslations).not.toHaveBeenCalled();
+        });
+
+        it('should load translations from nested manifest.translations', async () => {
+            const bundle = {
+                manifest: {
+                    id: 'com.test.nested',
+                    translations: [
+                        { en: { messages: { save: 'Save' } } },
+                    ],
+                },
+            };
+            const plugin = new AppPlugin(bundle);
+            await plugin.start!(mockContext);
+
+            expect(mockI18n.loadTranslations).toHaveBeenCalledWith('en', { messages: { save: 'Save' } });
+        });
+
+        it('should load multiple translation bundles', async () => {
+            const bundle = {
+                id: 'com.test.multi',
+                translations: [
+                    { en: { objects: { task: { label: 'Task' } } } },
+                    { en: { objects: { contact: { label: 'Contact' } } }, 'ja-JP': { objects: { contact: { label: '連絡先' } } } },
+                ],
+            };
+            const plugin = new AppPlugin(bundle);
+            await plugin.start!(mockContext);
+
+            expect(mockI18n.loadTranslations).toHaveBeenCalledTimes(3);
+        });
+    });
 });
diff --git a/packages/runtime/src/app-plugin.ts b/packages/runtime/src/app-plugin.ts
@@ -2,7 +2,7 @@
 
 import { Plugin, PluginContext } from '@objectstack/core';
 import { SeedLoaderService } from './seed-loader.js';
-import type { IMetadataService } from '@objectstack/spec/contracts';
+import type { IMetadataService, II18nService } from '@objectstack/spec/contracts';
 
 /**
  * AppPlugin
@@ -12,6 +12,7 @@ import type { IMetadataService } from '@objectstack/spec/contracts';
  * Responsibilities:
  * 1. Register App Manifest as a service (for ObjectQL discovery)
  * 2. Execute Runtime `onEnable` hook (for code logic)
+ * 3. Auto-load i18n translation bundles into the kernel's i18n service
  */
 export class AppPlugin implements Plugin {
     name: string;
@@ -102,6 +103,11 @@ export class AppPlugin implements Plugin {
              ctx.logger.debug('No runtime.onEnable function found', { appId });
         }
 
+        // ── i18n Translation Loading ─────────────────────────────────────
+        // Auto-load translation bundles from the app config into the
+        // kernel's i18n service, so discovery and handlers stay consistent.
+        this.loadTranslations(ctx, appId);
+
         // Data Seeding
         // Collect seed data from multiple locations (top-level `data` preferred, `manifest.data` for backward compat)
         const seedDatasets: any[] = [];
@@ -185,4 +191,54 @@ export class AppPlugin implements Plugin {
              }
         }
     }
+
+    /**
+     * Auto-load i18n translation bundles from the app config into the
+     * kernel's i18n service. Handles both `translations` (array of
+     * TranslationBundle) and `i18n` config (default locale, etc.).
+     *
+     * Gracefully skips when the i18n service is not registered —
+     * this keeps AppPlugin resilient across server/dev/mock environments.
+     */
+    private loadTranslations(ctx: PluginContext, appId: string): void {
+        const i18nService = ctx.getService('i18n') as II18nService | undefined;
+        if (!i18nService) {
+            ctx.logger.debug('[i18n] No i18n service registered; skipping translation loading', { appId });
+            return;
+        }
+
+        // Apply i18n config (default locale, etc.)
+        const i18nConfig = this.bundle.i18n || (this.bundle.manifest || this.bundle)?.i18n;
+        if (i18nConfig?.defaultLocale && typeof i18nService.setDefaultLocale === 'function') {
+            i18nService.setDefaultLocale(i18nConfig.defaultLocale);
+            ctx.logger.debug('[i18n] Set default locale', { appId, locale: i18nConfig.defaultLocale });
+        }
+
+        // Collect translation bundles from top-level and legacy locations
+        const bundles: Array<Record<string, unknown>> = [];
+        if (Array.isArray(this.bundle.translations)) {
+            bundles.push(...this.bundle.translations);
+        }
+        const manifest = this.bundle.manifest || this.bundle;
+        if (manifest && Array.isArray(manifest.translations) && manifest.translations !== this.bundle.translations) {
+            bundles.push(...manifest.translations);
+        }
+
+        if (bundles.length === 0) {
+            return;
+        }
+
+        let loadedLocales = 0;
+        for (const bundle of bundles) {
+            // Each bundle is a TranslationBundle: Record<locale, TranslationData>
+            for (const [locale, data] of Object.entries(bundle)) {
+                if (data && typeof data === 'object') {
+                    i18nService.loadTranslations(locale, data as Record<string, unknown>);
+                    loadedLocales++;
+                }
+            }
+        }
+
+        ctx.logger.info('[i18n] Loaded translation bundles', { appId, bundles: bundles.length, locales: loadedLocales });
+    }
 }
diff --git a/packages/runtime/src/http-dispatcher.test.ts b/packages/runtime/src/http-dispatcher.test.ts
