@objectstack/runtime 3.2.4 → 3.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/runtime",
-  "version": "3.2.4",
+  "version": "3.2.6",
   "license": "Apache-2.0",
   "description": "ObjectStack Core Runtime & Query Engine",
   "type": "module",
@@ -15,10 +15,10 @@
   },
   "dependencies": {
     "zod": "^4.3.6",
-    "@objectstack/core": "3.2.4",
-    "@objectstack/rest": "3.2.4",
-    "@objectstack/spec": "3.2.4",
-    "@objectstack/types": "3.2.4"
+    "@objectstack/core": "3.2.6",
+    "@objectstack/rest": "3.2.6",
+    "@objectstack/spec": "3.2.6",
+    "@objectstack/types": "3.2.6"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/src/app-plugin.test.ts

@@ -99,4 +99,171 @@ describe('AppPlugin', () => {
             expect.any(Object)
         );
     });
+
+    it('start should handle getService throwing for objectql', async () => {
+        const bundle = { id: 'com.test.throw' };
+        const plugin = new AppPlugin(bundle);
+        
+        vi.mocked(mockContext.getService).mockImplementation(() => {
+            throw new Error("[Kernel] Service 'objectql' not found");
+        });
+        
+        await plugin.start!(mockContext);
+        
+        expect(mockContext.logger.warn).toHaveBeenCalledWith(
+            expect.stringContaining('ObjectQL engine service not found'), 
+            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 warning (translations exist but no i18n service) and not throw
+            expect(mockContext.logger.warn).toHaveBeenCalledWith(
+                expect.stringContaining('no i18n service is registered')
+            );
+        });
+
+        it('should skip translation loading when getService throws for i18n', async () => {
+            vi.mocked(mockContext.getService).mockImplementation((name: string) => {
+                if (name === 'objectql') return mockQL;
+                throw new Error("[Kernel] Service 'i18n' not found");
+            });
+
+            const bundle = {
+                id: 'com.test.i18nthrow',
+                translations: [{ en: { messages: { hello: 'Hello' } } }],
+            };
+            const plugin = new AppPlugin(bundle);
+            await plugin.start!(mockContext);
+
+            // Should log warning (translations exist but no i18n service) and not throw
+            expect(mockContext.logger.warn).toHaveBeenCalledWith(
+                expect.stringContaining('no i18n service is registered')
+            );
+        });
+
+        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' })
+            );
+        });
+    });
 });

package/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;
@@ -59,9 +60,15 @@ export class AppPlugin implements Plugin {
         
         // Execute Runtime Step
         // Retrieve ObjectQL engine from services
-        // We cast to any/ObjectQL because ctx.getService returns unknown
-        const ql = ctx.getService('objectql') as any;
-        
+        // ctx.getService throws when a service is not registered, so we
+        // must use try/catch instead of a null-check.
+        let ql: any;
+        try {
+            ql = ctx.getService('objectql');
+        } catch {
+            // Service not registered — handled below
+        }
+
         if (!ql) {
             ctx.logger.warn('ObjectQL engine service not found', { 
                 appName: this.name,
@@ -102,6 +109,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 +197,84 @@ 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 {
+        // ctx.getService throws when a service is not registered, so we
+        // must use try/catch to gracefully skip when no i18n plugin is loaded.
+        let i18nService: II18nService | undefined;
+        try {
+            i18nService = ctx.getService('i18n') as II18nService;
+        } catch {
+            // Service not registered — handled below
+        }
+
+        // Collect translation bundles early to determine if we have data
+        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 (!i18nService) {
+            if (bundles.length > 0) {
+                ctx.logger.warn(
+                    `[i18n] App "${appId}" has ${bundles.length} translation bundle(s) but no i18n service is registered. ` +
+                    'Translations will not be served via REST API. ' +
+                    'Register I18nServicePlugin from @objectstack/service-i18n, or use DevPlugin ' +
+                    'which auto-detects translations and registers the i18n service automatically.'
+                );
+            } else {
+                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 });
+        }
+
+        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') {
+                    try {
+                        i18nService.loadTranslations(locale, data as Record<string, unknown>);
+                        loadedLocales++;
+                    } catch (err: any) {
+                        ctx.logger.warn('[i18n] Failed to load translations', { appId, locale, error: err.message });
+                    }
+                }
+            }
+        }
+
+        // Emit diagnostic when the active i18n service is a fallback/stub
+        const svcAny = i18nService as unknown as Record<string, unknown>;
+        if (svcAny._fallback || svcAny._dev) {
+            ctx.logger.info(
+                `[i18n] Loaded ${loadedLocales} locale(s) into in-memory i18n fallback for "${appId}". ` +
+                'For production, consider registering I18nServicePlugin from @objectstack/service-i18n.'
+            );
+        } else {
+            ctx.logger.info('[i18n] Loaded translation bundles', { appId, bundles: bundles.length, locales: loadedLocales });
+        }
+    }
 }

package/src/dispatcher-plugin.ts

@@ -53,7 +53,7 @@ function errorResponse(err: any, res: any): void {
  *   - /graphql   (GraphQL)
  *   - /analytics (BI queries)
  *   - /packages  (package management)
-
+ *   - /i18n      (internationalization — locales, translations, field labels)
  *   - /storage   (file storage)
  *   - /automation (CRUD + triggers + runs)
  *
@@ -88,12 +88,12 @@ export function createDispatcherPlugin(config: DispatcherPluginConfig = {}): Plu
 
             // ── Discovery (.well-known) ─────────────────────────────────
             server.get('/.well-known/objectstack', async (_req: any, res: any) => {
-                res.json({ data: dispatcher.getDiscoveryInfo(prefix) });
+                res.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
             });
 
             // ── Discovery (versioned API path) ──────────────────────────
             server.get(`${prefix}/discovery`, async (_req: any, res: any) => {
-                res.json({ data: dispatcher.getDiscoveryInfo(prefix) });
+                res.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
             });
 
             // ── Auth ────────────────────────────────────────────────────
@@ -237,6 +237,36 @@ export function createDispatcherPlugin(config: DispatcherPluginConfig = {}): Plu
                 }
             });
 
+            // ── i18n ────────────────────────────────────────────────────
+            // Bridges to HttpDispatcher.handleI18n() which resolves the i18n
+            // service from the kernel (either I18nServicePlugin or memory fallback).
+            server.get(`${prefix}/i18n/locales`, async (req: any, res: any) => {
+                try {
+                    const result = await dispatcher.handleI18n('/locales', 'GET', req.query, { request: req });
+                    sendResult(result, res);
+                } catch (err: any) {
+                    errorResponse(err, res);
+                }
+            });
+
+            server.get(`${prefix}/i18n/translations/:locale`, async (req: any, res: any) => {
+                try {
+                    const result = await dispatcher.handleI18n(`/translations/${req.params.locale}`, 'GET', req.query, { request: req });
+                    sendResult(result, res);
+                } catch (err: any) {
+                    errorResponse(err, res);
+                }
+            });
+
+            server.get(`${prefix}/i18n/labels/:object/:locale`, async (req: any, res: any) => {
+                try {
+                    const result = await dispatcher.handleI18n(`/labels/${req.params.object}/${req.params.locale}`, 'GET', req.query, { request: req });
+                    sendResult(result, res);
+                } catch (err: any) {
+                    errorResponse(err, res);
+                }
+            });
+
             // ── Automation ──────────────────────────────────────────────
             server.get(`${prefix}/automation`, async (req: any, res: any) => {
                 try {

package/src/http-dispatcher.test.ts

@@ -953,5 +953,259 @@ describe('HttpDispatcher', () => {
             expect(result.handled).toBe(true);
             expect(result.response?.body?.data?.locales).toEqual(['en', 'zh-CN', 'ja']);
         });
+
+        it('should resolve locale via fallback (zh → zh-CN) for translations', async () => {
+            // Override mock to be locale-aware: only 'zh-CN' has data, 'zh' returns empty
+            mockI18nService.getTranslations = vi.fn().mockImplementation((locale: string) => {
+                if (locale === 'zh-CN') return { 'o.task.label': '任务' };
+                return {};
+            });
+
+            const result = await dispatcher.handleI18n('/translations/zh', 'GET', {}, { request: {} });
+            expect(result.handled).toBe(true);
+            expect(result.response?.status).toBe(200);
+            const data = result.response?.body?.data;
+            expect(data.locale).toBe('zh-CN');
+            expect(data.requestedLocale).toBe('zh');
+            expect(data.translations).toEqual({ 'o.task.label': '任务' });
+        });
+
+        it('should resolve locale via case-insensitive fallback (ZH-CN → zh-CN) for translations', async () => {
+            // Override mock to be locale-aware: 'ZH-CN' returns empty, 'zh-CN' has data
+            mockI18nService.getTranslations = vi.fn().mockImplementation((locale: string) => {
+                if (locale === 'zh-CN') return { 'o.task.label': '任务' };
+                return {};
+            });
+
+            const result = await dispatcher.handleI18n('/translations/ZH-CN', 'GET', {}, { request: {} });
+            expect(result.handled).toBe(true);
+            expect(result.response?.status).toBe(200);
+            const data = result.response?.body?.data;
+            expect(data.locale).toBe('zh-CN');
+            expect(data.translations).toEqual({ 'o.task.label': '任务' });
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════
+    // Discovery ↔ Handler i18n consistency
+    // ═══════════════════════════════════════════════════════════════
+
+    describe('discovery-handler i18n consistency', () => {
+        it('should report i18n as available in discovery when service is registered', async () => {
+            const mockI18nService = {
+                getLocales: vi.fn().mockReturnValue(['en', 'zh-CN', 'ja']),
+                getTranslations: vi.fn().mockReturnValue({}),
+                getDefaultLocale: vi.fn().mockReturnValue('en'),
+            };
+
+            (kernel as any).getService = vi.fn().mockImplementation((name: string) => {
+                if (name === 'i18n') return mockI18nService;
+                return null;
+            });
+
+            const info = await dispatcher.getDiscoveryInfo('/api/v1');
+            expect(info.services.i18n.enabled).toBe(true);
+            expect(info.services.i18n.status).toBe('available');
+            expect(info.routes.i18n).toBe('/api/v1/i18n');
+            expect(info.features.i18n).toBe(true);
+        });
+
+        it('should report i18n as unavailable in discovery when service is not registered', async () => {
+            (kernel as any).getService = vi.fn().mockResolvedValue(null);
+            (kernel as any).services = new Map();
+
+            const info = await dispatcher.getDiscoveryInfo('/api/v1');
+            expect(info.services.i18n.enabled).toBe(false);
+            expect(info.services.i18n.status).toBe('unavailable');
+            expect(info.routes.i18n).toBeUndefined();
+            expect(info.features.i18n).toBe(false);
+        });
+
+        it('should detect i18n via getServiceAsync (async factory) in discovery', async () => {
+            const mockI18nService = {
+                getLocales: vi.fn().mockReturnValue(['en', 'fr']),
+                getTranslations: vi.fn().mockReturnValue({}),
+                getDefaultLocale: vi.fn().mockReturnValue('fr'),
+            };
+
+            // Service NOT in sync map, only accessible via async factory
+            (kernel as any).services = new Map();
+            (kernel as any).getServiceAsync = vi.fn().mockImplementation(async (name: string) => {
+                if (name === 'i18n') return mockI18nService;
+                return null;
+            });
+
+            const info = await dispatcher.getDiscoveryInfo('/api/v1');
+            expect(info.services.i18n.enabled).toBe(true);
+            expect(info.services.i18n.status).toBe('available');
+
+            // Handler should also find it
+            const result = await dispatcher.handleI18n('/locales', 'GET', {}, { request: {} });
+            expect(result.handled).toBe(true);
+            expect(result.response?.status).toBe(200);
+            expect(result.response?.body?.data?.locales).toEqual(['en', 'fr']);
+        });
+
+        it('should populate locale from actual i18n service', async () => {
+            const mockI18nService = {
+                getLocales: vi.fn().mockReturnValue(['en', 'zh-CN', 'ja']),
+                getTranslations: vi.fn().mockReturnValue({}),
+                getDefaultLocale: vi.fn().mockReturnValue('zh-CN'),
+            };
+
+            (kernel as any).getService = vi.fn().mockImplementation((name: string) => {
+                if (name === 'i18n') return mockI18nService;
+                return null;
+            });
+
+            const info = await dispatcher.getDiscoveryInfo('/api/v1');
+            expect(info.locale.default).toBe('zh-CN');
+            expect(info.locale.supported).toEqual(['en', 'zh-CN', 'ja']);
+        });
+
+        it('should use default locale when i18n service is not available', async () => {
+            (kernel as any).getService = vi.fn().mockResolvedValue(null);
+            (kernel as any).services = new Map();
+
+            const info = await dispatcher.getDiscoveryInfo('/api/v1');
+            expect(info.locale.default).toBe('en');
+            expect(info.locale.supported).toEqual(['en']);
+            expect(info.locale.timezone).toBe('UTC');
+        });
+
+        it('should ensure discovery and dispatch are consistent for root path', async () => {
+            const mockI18nService = {
+                getLocales: vi.fn().mockReturnValue(['en']),
+                getTranslations: vi.fn().mockReturnValue({}),
+                getDefaultLocale: vi.fn().mockReturnValue('en'),
+            };
+
+            (kernel as any).getService = vi.fn().mockImplementation((name: string) => {
+                if (name === 'i18n') return mockI18nService;
+                return null;
+            });
+
+            // Dispatch to root should return the same discovery data
+            const result = await dispatcher.dispatch('GET', '', undefined, {}, { request: {} });
+            expect(result.handled).toBe(true);
+            const data = result.response?.body?.data;
+            expect(data.services.i18n.enabled).toBe(true);
+            expect(data.locale.default).toBe('en');
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════
+    // i18n across server/dev/mock environments
+    // ═══════════════════════════════════════════════════════════════
+
+    describe('i18n environment consistency', () => {
+        it('should work with dev stub i18n service (in-memory translations)', async () => {
+            // Simulate dev plugin i18n stub — Map-backed, all sync
+            const translations = new Map<string, Record<string, unknown>>();
+            let defaultLocale = 'en';
+            const devI18nStub = {
+                t: (key: string, locale: string) => {
+                    const t = translations.get(locale);
+                    return (t?.[key] as string) ?? key;
+                },
+                getTranslations: (locale: string) => translations.get(locale) ?? {},
+                loadTranslations: (locale: string, data: Record<string, unknown>) => {
+                    translations.set(locale, { ...translations.get(locale), ...data });
+                },
+                getLocales: () => [...translations.keys()],
+                getDefaultLocale: () => defaultLocale,
+                setDefaultLocale: (locale: string) => { defaultLocale = locale; },
+            };
+
+            // Load data like AppPlugin would
+            devI18nStub.loadTranslations('en', { 'o.task.label': 'Task' });
+            devI18nStub.loadTranslations('zh-CN', { 'o.task.label': '任务' });
+
+            (kernel as any).getService = vi.fn().mockImplementation((name: string) => {
+                if (name === 'i18n') return devI18nStub;
+                return null;
+            });
+
+            // Discovery should reflect loaded locales
+            const info = await dispatcher.getDiscoveryInfo('/api/v1');
+            expect(info.services.i18n.enabled).toBe(true);
+            expect(info.locale.supported).toEqual(['en', 'zh-CN']);
+
+            // Handler should serve translations
+            const result = await dispatcher.handleI18n('/translations/zh-CN', 'GET', {}, { request: {} });
+            expect(result.response?.status).toBe(200);
+            expect(result.response?.body?.data?.translations['o.task.label']).toBe('任务');
+        });
+
+        it('should handle MSW catch-all dispatch pattern for i18n', async () => {
+            // MSW routes all requests through dispatcher.dispatch()
+            const mockI18nService = {
+                getLocales: vi.fn().mockReturnValue(['en', 'de']),
+                getTranslations: vi.fn().mockReturnValue({ 'o.account.label': 'Konto' }),
+                getDefaultLocale: vi.fn().mockReturnValue('de'),
+            };
+
+            (kernel as any).getService = vi.fn().mockImplementation((name: string) => {
+                if (name === 'i18n') return mockI18nService;
+                return null;
+            });
+
+            // MSW-style dispatch: full path stripped to relative
+            const localesResult = await dispatcher.dispatch('GET', '/i18n/locales', undefined, {}, { request: {} });
+            expect(localesResult.handled).toBe(true);
+            expect(localesResult.response?.body?.data?.locales).toEqual(['en', 'de']);
+
+            const translationsResult = await dispatcher.dispatch('GET', '/i18n/translations/de', undefined, {}, { request: {} });
+            expect(translationsResult.handled).toBe(true);
+            expect(translationsResult.response?.body?.data?.translations['o.account.label']).toBe('Konto');
+
+            // Discovery and handler agree
+            const discovery = await dispatcher.getDiscoveryInfo('/api/v1');
+            expect(discovery.services.i18n.enabled).toBe(true);
+            expect(discovery.locale.default).toBe('de');
+        });
+
+        it('should return 501 consistently when i18n is unavailable in both discovery and handler', async () => {
+            (kernel as any).getService = vi.fn().mockResolvedValue(null);
+            (kernel as any).services = new Map();
+
+            // Discovery: unavailable
+            const info = await dispatcher.getDiscoveryInfo('/api/v1');
+            expect(info.services.i18n.enabled).toBe(false);
+            expect(info.services.i18n.status).toBe('unavailable');
+
+            // Handler: 501
+            const result = await dispatcher.handleI18n('/locales', 'GET', {}, { request: {} });
+            expect(result.response?.status).toBe(501);
+
+            // Dispatch: also 501
+            const dispatchResult = await dispatcher.dispatch('GET', '/i18n/locales', undefined, {}, { request: {} });
+            expect(dispatchResult.response?.status).toBe(501);
+        });
+
+        it('should handle context-based service resolution (mock kernel)', async () => {
+            // Simulate a kernel that only provides i18n through context.getService
+            const mockI18n = {
+                getLocales: vi.fn().mockReturnValue(['en']),
+                getTranslations: vi.fn().mockReturnValue({}),
+                getDefaultLocale: vi.fn().mockReturnValue('en'),
+            };
+
+            (kernel as any).services = new Map();
+            (kernel as any).getService = undefined;
+            (kernel as any).getServiceAsync = undefined;
+            (kernel as any).context = {
+                getService: vi.fn().mockImplementation((name: string) => {
+                    if (name === 'i18n') return mockI18n;
+                    return null;
+                }),
+            };
+
+            const info = await dispatcher.getDiscoveryInfo('/api/v1');
+            expect(info.services.i18n.enabled).toBe(true);
+
+            const result = await dispatcher.handleI18n('/locales', 'GET', {}, { request: {} });
+            expect(result.response?.status).toBe(200);
+        });
     });
 });