Merge pull request #1107 from objectstack-ai/copilot/unify-i18n-plugin-loading

Author: hotlong

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Unified i18n Plugin Loading & Translation Injection** (`examples/crm`, `apps/console`): Unified the i18n loading mechanism so that both server and MSW/mock environments use the same translation pipeline. CRM's `objectstack.config.ts` now declares its translations via `i18n: { namespace: 'crm', translations: crmLocales }`. The shared config (`objectstack.shared.ts`) merges i18n bundles from all composed stacks. `createKernel` registers an i18n kernel service from the config bundles and auto-generates the `/api/v1/i18n/translations/:lang` MSW handler, returning translations in the standard `{ data: { locale, translations } }` spec envelope. Removed all manually-maintained i18n custom handlers and duplicate `loadAppLocale` functions from `browser.ts` and `server.ts`. The broker shim now supports `i18n.getTranslations` for server-side dispatch.
+
 - **ObjectDataTable: columns now support `string[]` shorthand** (`@object-ui/plugin-dashboard`): `ObjectDataTable` now normalizes `columns` entries so that both `string[]` (e.g. `['name', 'close_date']`) and `object[]` formats are accepted. String entries are automatically converted to `{ header, accessorKey }` objects with title-cased headers derived from snake_case and camelCase field names. Previously, passing a `string[]` caused the downstream `data-table` renderer to crash when accessing `col.accessorKey` on a plain string. Mixed arrays (some strings, some objects) are also handled correctly. Includes 8 new unit tests.
 
 ### Fixed

apps/console/objectstack.shared.ts

@@ -24,6 +24,12 @@ const allConfigs = [crmConfig, todoConfig, kitchenSinkConfig];
 // so we collect data from all stacks before composing).
 const allData = allConfigs.flatMap((c: any) => c.manifest?.data || c.data || []);
 
+// Aggregate i18n bundles from all stacks that declare an i18n section.
+// Each bundle carries a namespace (e.g. 'crm') and per-language translations.
+const i18nBundles = allConfigs
+  .map((c: any) => c.i18n)
+  .filter((i: any) => i?.namespace && i?.translations);
+
 // Protocol-level composition via @objectstack/spec: handles object dedup,
 // array concatenation, actions→objects mapping, and manifest selection.
 const composed = composeStacks(allConfigs as any[], { objectConflict: 'override' }) as any;
@@ -89,6 +95,9 @@ export const sharedConfig = {
     name: '@object-ui/console',
     data: allData,
   },
+  i18n: {
+    bundles: i18nBundles,
+  },
   plugins: [],
   datasources: [
     {

apps/console/src/mocks/browser.ts

@@ -6,10 +6,12 @@
  * via MSW. This ensures filter/sort/top/pagination work identically to
  * server mode.
  *
+ * i18n translations are resolved automatically by createKernel from the
+ * `i18n.bundles` field in the app config — no manual handler required.
+ *
  * This pattern follows @objectstack/studio — see https://github.com/objectstack-ai/spec
  */
 
-import { http, HttpResponse } from 'msw';
 import { setupWorker } from 'msw/browser';
 import { ObjectKernel } from '@objectstack/runtime';
 import { InMemoryDriver } from '@objectstack/driver-memory';
@@ -23,22 +25,6 @@ let driver: InMemoryDriver | null = null;
 let mswPlugin: MSWPlugin | null = null;
 let worker: ReturnType<typeof setupWorker> | null = null;
 
-/**
- * Load application-specific locale bundles for the i18n API endpoint.
- * In this mock environment, loads translations from installed example packages.
- * Returns a flat translation resource for the given language code.
- */
-async function loadAppLocale(lang: string): Promise<Record<string, unknown>> {
-  try {
-    const { crmLocales } = await import('@object-ui/example-crm');
-    const translations = (crmLocales as Record<string, any>)[lang];
-    if (!translations) return {};
-    return { crm: translations };
-  } catch {
-    return {};
-  }
-}
-
 export async function startMockServer() {
   // Polyfill process.on for ObjectKernel in browser environment
   try {
@@ -65,12 +51,6 @@ export async function startMockServer() {
       customHandlers: [
         // Mock auth endpoints (better-auth compatible)
         ...createAuthHandlers('/api/v1/auth'),
-        // Serve i18n translation bundles via API
-        http.get('/api/v1/i18n/translations/:lang', async ({ params }) => {
-          const lang = params.lang as string;
-          const resources = await loadAppLocale(lang);
-          return HttpResponse.json(resources);
-        }),
       ],
     },
   });

apps/console/src/mocks/createKernel.ts

@@ -18,6 +18,7 @@ import { InMemoryDriver, MemoryAnalyticsService } from '@objectstack/driver-memo
 import { MSWPlugin } from '@objectstack/plugin-msw';
 import type { MSWPluginOptions } from '@objectstack/plugin-msw';
 import type { Cube } from '@objectstack/spec/data';
+import { http, HttpResponse } from 'msw';
 
 export interface KernelOptions {
   /** Application configuration (defineStack output) */
@@ -111,6 +112,15 @@ async function installBrokerShim(kernel: ObjectKernel): Promise<void> {
         }
       }
 
+      // i18n service calls (e.g. i18n.getTranslations)
+      if (service === 'i18n') {
+        let i18nService: any;
+        try { i18nService = await kernel.getService('i18n'); } catch { /* noop */ }
+        if (i18nService) {
+          if (method === 'getTranslations') return i18nService.getTranslations(params?.lang);
+        }
+      }
+
       throw new Error(`[BrokerShim] Unhandled action: ${action}`);
     },
   };
@@ -247,6 +257,38 @@ function buildCubesFromConfig(appConfig: any): Cube[] {
   return cubes;
 }
 
+/** Per-language translation map: language code → translation tree. */
+type TranslationMap = Record<string, Record<string, unknown>>;
+
+/** A named translation bundle as declared in a stack's i18n config. */
+interface I18nBundle {
+  namespace: string;
+  translations: TranslationMap;
+}
+
+/**
+ * Resolve translations for a given language from the i18n bundles
+ * declared in the application configuration.
+ *
+ * Each bundle carries a `namespace` (e.g. "crm") and a `translations`
+ * map keyed by language code.  The resolved output nests each bundle's
+ * translations under its namespace so that i18next sees keys like
+ * `crm.objects.account.label`.
+ */
+function resolveI18nTranslations(
+  bundles: I18nBundle[],
+  lang: string,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = {};
+  for (const bundle of bundles) {
+    const langTranslations = bundle.translations[lang];
+    if (langTranslations) {
+      merged[bundle.namespace] = langTranslations;
+    }
+  }
+  return merged;
+}
+
 /**
  * Create and bootstrap an ObjectStack kernel with in-memory driver.
  *
@@ -282,14 +324,52 @@ export async function createKernel(options: KernelOptions): Promise<KernelResult
     generateSql: (query: any) => memoryAnalytics.generateSql(query),
   });
 
+  // ── i18n service registration ──────────────────────────────────────
+  // Read translation bundles from the app config (populated by each stack's
+  // `i18n: { namespace, translations }` field and merged via sharedConfig).
+  // This ensures both MSW/mock and server modes share the same translation
+  // resolution pipeline — no manual per-environment i18n handlers required.
+  const i18nBundles: I18nBundle[] = appConfig.i18n?.bundles ?? [];
+
+  if (i18nBundles.length > 0) {
+    kernel.registerService('i18n', {
+      getTranslations: (lang: string) => ({
+        locale: lang,
+        translations: resolveI18nTranslations(i18nBundles, lang),
+      }),
+    });
+  }
+
   let mswPlugin: MSWPlugin | undefined;
   if (mswOptions) {
     // Install a protocol-based broker shim BEFORE MSWPlugin's start phase
     // so that HttpDispatcher (inside MSWPlugin) can resolve data/metadata
     // calls without requiring a full Moleculer broker.
     await installBrokerShim(kernel);
 
-    mswPlugin = new MSWPlugin(mswOptions);
+    // Auto-inject the i18n REST handler when translations are declared in
+    // the app config, so callers (browser.ts / server.ts) no longer need
+    // to manually construct a custom i18n MSW route.
+    const effectiveOptions = { ...mswOptions };
+    if (i18nBundles.length > 0) {
+      const baseUrl = mswOptions.baseUrl ?? '';
+      const i18nHandler = http.get(
+        `${baseUrl}/i18n/translations/:lang`,
+        ({ params }) => {
+          const lang = params.lang as string;
+          const translations = resolveI18nTranslations(i18nBundles, lang);
+          return HttpResponse.json({
+            data: { locale: lang, translations },
+          });
+        },
+      );
+      effectiveOptions.customHandlers = [
+        i18nHandler,
+        ...(mswOptions.customHandlers ?? []),
+      ];
+    }
+
+    mswPlugin = new MSWPlugin(effectiveOptions);
     await kernel.use(mswPlugin);
   }
 

apps/console/src/mocks/server.ts

@@ -6,10 +6,12 @@
  * full ObjectStack protocol, so filter/sort/top/pagination work
  * identically to server mode.
  *
+ * i18n translations are resolved automatically by createKernel from the
+ * `i18n.bundles` field in the app config — no manual handler required.
+ *
  * This pattern follows @objectstack/studio — see https://github.com/objectstack-ai/spec
  */
 
-import { http, HttpResponse } from 'msw';
 import { ObjectKernel } from '@objectstack/runtime';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 import { setupServer } from 'msw/node';
@@ -23,21 +25,6 @@ let driver: InMemoryDriver | null = null;
 let mswPlugin: MSWPlugin | null = null;
 let server: ReturnType<typeof setupServer> | null = null;
 
-/**
- * Load application-specific locale bundles for the i18n API endpoint.
- * In this mock environment, loads translations from installed example packages.
- */
-async function loadAppLocale(lang: string): Promise<Record<string, unknown>> {
-  try {
-    const { crmLocales } = await import('@object-ui/example-crm');
-    const translations = (crmLocales as Record<string, any>)[lang];
-    if (!translations) return {};
-    return { crm: translations };
-  } catch {
-    return {};
-  }
-}
-
 export async function startMockServer() {
   if (kernel) {
     console.log('[MSW] ObjectStack Runtime already initialized');
@@ -56,11 +43,6 @@ export async function startMockServer() {
       customHandlers: [
         // Mock auth endpoints (better-auth compatible)
         ...createAuthHandlers('/api/v1/auth'),
-        http.get('/api/v1/i18n/translations/:lang', async ({ params }) => {
-          const lang = params.lang as string;
-          const resources = await loadAppLocale(lang);
-          return HttpResponse.json(resources);
-        }),
       ],
     },
   });

examples/crm/objectstack.config.ts

@@ -9,6 +9,7 @@ import { UserObject } from './src/objects/user.object';
 import { ProjectObject } from './src/objects/project.object';
 import { EventObject } from './src/objects/event.object';
 import { OpportunityContactObject } from './src/objects/opportunity_contact.object';
+import { crmLocales } from './src/i18n';
 import { AccountView } from './src/views/account.view';
 import { ContactView } from './src/views/contact.view';
 import { OpportunityView } from './src/views/opportunity.view';
@@ -118,5 +119,11 @@ export default defineStack({
       OpportunityContactData,
     ]
   },
+  i18n: {
+    defaultLocale: 'en',
+    supportedLocales: ['en', 'zh', 'ja', 'ko', 'de', 'fr', 'es', 'pt', 'ru', 'ar'],
+    namespace: 'crm',
+    translations: crmLocales,
+  } as any,
   plugins: [],
 }, { strict: false }); // Defer validation to `objectstack compile` CLI