Merge pull request #903 from objectstack-ai/copilot/fix-i18n-service-consistency

hotlong · web-flow · commit 473e77d290c1 · 2026-03-11T12:18:33.000+08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- **i18n service registration & state inconsistency** — Discovery API (`getDiscoveryInfo`) now uses
+  the same async `resolveService()` fallback chain that request handlers (`handleI18n`) use, ensuring
+  the reported service status is always consistent with actual runtime availability.
+- Discovery `locale` field is now populated from the actual i18n service (`getDefaultLocale`,
+  `getLocales`) instead of being hardcoded, so clients get accurate locale information.
+- 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/adapters/express/src/index.ts b/packages/adapters/express/src/index.ts
@@ -71,8 +71,8 @@ export function createExpressRouter(options: ExpressAdapterOptions): Router {
   };
 
   // --- Discovery ---
-  router.get('/', (_req: Request, res: Response) => {
-    res.json({ data: dispatcher.getDiscoveryInfo(prefix) });
+  router.get('/', async (_req: Request, res: Response) => {
+    res.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
   });
 
   // --- Auth ---
diff --git a/packages/adapters/fastify/src/index.ts b/packages/adapters/fastify/src/index.ts
@@ -70,7 +70,7 @@ export async function objectStackPlugin(fastify: FastifyInstance, options: Fasti
 
   // --- Discovery ---
   fastify.get(`${prefix}`, async (_request: FastifyRequest, reply: FastifyReply) => {
-    return reply.send({ data: dispatcher.getDiscoveryInfo(prefix) });
+    return reply.send({ data: await dispatcher.getDiscoveryInfo(prefix) });
   });
 
   // --- .well-known ---
diff --git a/packages/adapters/hono/src/index.ts b/packages/adapters/hono/src/index.ts
@@ -72,8 +72,8 @@ export function createHonoApp(options: ObjectStackHonoOptions): Hono {
   };
 
   // --- Discovery ---
-  app.get(`${prefix}`, (c) => {
-    return c.json({ data: dispatcher.getDiscoveryInfo(prefix) });
+  app.get(`${prefix}`, async (c) => {
+    return c.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
   });
 
   // --- .well-known ---
diff --git a/packages/adapters/nestjs/src/__mocks__/runtime.ts b/packages/adapters/nestjs/src/__mocks__/runtime.ts
@@ -2,7 +2,7 @@
 import { vi } from 'vitest';
 
 export class HttpDispatcher {
-  getDiscoveryInfo = vi.fn().mockReturnValue({ version: '1.0' });
+  getDiscoveryInfo = vi.fn().mockResolvedValue({ version: '1.0' });
   handleGraphQL = vi.fn().mockResolvedValue({ data: {} });
   handleAuth = vi.fn().mockResolvedValue({ handled: true, response: { status: 200, body: { ok: true } } });
   handleMetadata = vi.fn().mockResolvedValue({ handled: true, response: { status: 200, body: [] } });
diff --git a/packages/adapters/nestjs/src/index.ts b/packages/adapters/nestjs/src/index.ts
@@ -95,8 +95,8 @@ export class ObjectStackController {
 
   // --- Discovery Endpoint ---
   @Get()
-  discovery() {
-    return { data: this.service.dispatcher.getDiscoveryInfo('/api') };
+  async discovery() {
+    return { data: await this.service.dispatcher.getDiscoveryInfo('/api') };
   }
 
   @Post('graphql')
diff --git a/packages/adapters/nestjs/src/nestjs.test.ts b/packages/adapters/nestjs/src/nestjs.test.ts
@@ -136,8 +136,8 @@ describe('ObjectStackController', () => {
   });
 
   describe('discovery()', () => {
-    it('returns discovery info from the dispatcher', () => {
-      const result = controller.discovery();
+    it('returns discovery info from the dispatcher', async () => {
+      const result = await controller.discovery();
       expect(result).toEqual({ data: { version: '1.0' } });
       expect(service.dispatcher.getDiscoveryInfo).toHaveBeenCalledWith('/api');
     });
diff --git a/packages/adapters/nextjs/src/index.ts b/packages/adapters/nextjs/src/index.ts
@@ -60,7 +60,7 @@ export function createRouteHandler(options: NextAdapterOptions) {
     
     // --- 0. Discovery Endpoint ---
     if (segments.length === 0 && method === 'GET') {
-      return NextResponse.json({ data: dispatcher.getDiscoveryInfo(options.prefix || '/api') });
+      return NextResponse.json({ data: await dispatcher.getDiscoveryInfo(options.prefix || '/api') });
     }
 
     try {
diff --git a/packages/adapters/nuxt/src/index.ts b/packages/adapters/nuxt/src/index.ts
@@ -82,8 +82,8 @@ export function createH3Router(options: NuxtAdapterOptions): Router {
   // --- Discovery ---
   router.get(
     `${prefix}`,
-    defineEventHandler(() => {
-      return { data: dispatcher.getDiscoveryInfo(prefix) };
+    defineEventHandler(async () => {
+      return { data: await dispatcher.getDiscoveryInfo(prefix) };
     }),
   );
 
diff --git a/packages/adapters/sveltekit/src/index.ts b/packages/adapters/sveltekit/src/index.ts
@@ -97,7 +97,7 @@ export function createRequestHandler(options: SvelteKitAdapterOptions) {
 
     // --- Discovery ---
     if (segments.length === 0 && method === 'GET') {
-      return new Response(JSON.stringify({ data: dispatcher.getDiscoveryInfo(prefix) }), {
+      return new Response(JSON.stringify({ data: await dispatcher.getDiscoveryInfo(prefix) }), {
         status: 200,
         headers: { 'Content-Type': 'application/json' },
       });
diff --git a/packages/plugins/plugin-msw/src/msw-plugin.ts b/packages/plugins/plugin-msw/src/msw-plugin.ts
@@ -204,10 +204,10 @@ export class MSWPlugin implements Plugin {
 
         // Discovery Endpoint
         this.handlers.push(
-            http.get('*/.well-known/objectstack', () => {
+            http.get('*/.well-known/objectstack', async () => {
                 if (this.dispatcher) {
                     return HttpResponse.json({
-                        data: this.dispatcher.getDiscoveryInfo(baseUrl)
+                        data: await this.dispatcher.getDiscoveryInfo(baseUrl)
                     });
                 }
                 return HttpResponse.json({
diff --git a/packages/runtime/src/app-plugin.test.ts b/packages/runtime/src/app-plugin.test.ts
@@ -99,4 +99,137 @@ 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);
+        });
+
+        it('should handle errors in loadTranslations gracefully', async () => {
+            mockI18n.loadTranslations.mockImplementation((locale: string) => {
+                if (locale === 'zh-CN') throw new Error('Disk read failed');
+            });
+
+            const bundle = {
+                id: 'com.test.error',
+                translations: [
+                    { en: { messages: { save: 'Save' } }, 'zh-CN': { messages: { save: '保存' } } },
+                ],
+            };
+            const plugin = new AppPlugin(bundle);
+            await plugin.start!(mockContext);
+
+            // en should still be loaded despite zh-CN failure
+            expect(mockI18n.loadTranslations).toHaveBeenCalledWith('en', { messages: { save: 'Save' } });
+            expect(mockContext.logger.warn).toHaveBeenCalledWith(
+                expect.stringContaining('Failed to load translations'),
+                expect.objectContaining({ locale: 'zh-CN' })
+            );
+        });
+    });
 });
diff --git a/packages/runtime/src/app-plugin.ts b/packages/runtime/src/app-plugin.ts
diff --git a/packages/runtime/src/dispatcher-plugin.ts b/packages/runtime/src/dispatcher-plugin.ts
diff --git a/packages/runtime/src/http-dispatcher.test.ts b/packages/runtime/src/http-dispatcher.test.ts
diff --git a/packages/runtime/src/http-dispatcher.ts b/packages/runtime/src/http-dispatcher.ts

Original file line number	Diff line number	Diff line change
`@@ -95,8 +95,8 @@ export class ObjectStackController {`
`95`	`95`
`96`	`96`	`// --- Discovery Endpoint ---`
`97`	`97`	`@Get()`
`98`		`- discovery() {`
`99`		`- return { data: this.service.dispatcher.getDiscoveryInfo('/api') };`
	`98`	`+ async discovery() {`
	`99`	`+ return { data: await this.service.dispatcher.getDiscoveryInfo('/api') };`
`100`	`100`	`}`
`101`	`101`
`102`	`102`	`@Post('graphql')`
Original file line number	Diff line number	Diff line change
`@@ -60,7 +60,7 @@ export function createRouteHandler(options: NextAdapterOptions) {`
`60`	`60`
`61`	`61`	`// --- 0. Discovery Endpoint ---`
`62`	`62`	`if (segments.length === 0 && method === 'GET') {`
`63`		`- return NextResponse.json({ data: dispatcher.getDiscoveryInfo(options.prefix \|\| '/api') });`
	`63`	`+ return NextResponse.json({ data: await dispatcher.getDiscoveryInfo(options.prefix \|\| '/api') });`
`64`	`64`	`}`
`65`	`65`
`66`	`66`	`try {`