fix(server): deprecate the i18n option the server never reads

.changeset/deprecate-server-i18n.md

@@ -0,0 +1,5 @@
+---
+"@chatcops/server": patch
+---
+
+Deprecate the `i18n` option, which the server never read. Setting it now logs a warning.

packages/server/src/config.ts

@@ -12,6 +12,7 @@ export interface ChatCopsServerConfig {
   analytics?: boolean;
   /** Allowed CORS origin. Defaults to `'*'`. */
   cors?: string;
+  /** @deprecated The server ignores this. Set the widget's text with its `strings` option. */
   i18n?: { defaultLocale: string; locales: Record<string, LocaleStrings> };
 }
 

packages/server/src/handler.ts

@@ -11,6 +11,10 @@ import { RateLimiter } from './rate-limit.js';
 import { WebhookDispatcher } from './webhook.js';
 
 export function createChatHandler(config: ChatCopsServerConfig) {
+  if (config.i18n) {
+    console.warn('[chatcops] The `i18n` option is deprecated and ignored. Set the widget text with its `strings` option.');
+  }
+
   const providerPromise = createProvider(config.provider);
   const conversations = new ConversationManager();
   const rateLimiter = config.rateLimit ? new RateLimiter(config.rateLimit) : new RateLimiter();

packages/server/tests/handler.test.ts

@@ -131,6 +131,32 @@ describe('createChatHandler', () => {
     expect(clearIntervalSpy).toHaveBeenCalledOnce();
   });
 
+  it('warns once when the deprecated i18n option is set', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const { cleanup } = createChatHandler({
+      provider: { type: 'openai', apiKey: 'test-key' },
+      systemPrompt: 'Test',
+      i18n: { defaultLocale: 'en', locales: {} },
+    });
+    cleanup();
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warnSpy.mock.calls[0][0]).toContain('i18n');
+  });
+
+  it('does not warn when i18n is not set', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const { cleanup } = createChatHandler({
+      provider: { type: 'openai', apiKey: 'test-key' },
+      systemPrompt: 'Test',
+    });
+    cleanup();
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
   it('passes a working tool executor into the streaming provider', async () => {
     const weatherTool = {
       name: 'get_weather',

website/src/content/docs/server/setup.mdx

@@ -64,12 +64,6 @@ const handler = chatcopsMiddleware({
 
   // Optional: CORS origin
   cors: '*',
-
-  // Optional: i18n (accepted, but the server doesn't read it yet)
-  i18n: {
-    defaultLocale: 'en',
-    locales: { /* custom strings */ },
-  },
 });
 ```
 
@@ -93,6 +87,7 @@ interface ChatCopsServerConfig {
   webhooks?: WebhookConfig[];
   analytics?: boolean;
   cors?: string;
+  /** @deprecated Ignored by the server. Use the widget's `strings` option. */
   i18n?: {
     defaultLocale: string;
     locales: Record<string, LocaleStrings>;

website/src/content/docs/widget/i18n.mdx

@@ -88,4 +88,4 @@ The server doesn't translate anything itself. When a request has a `locale`, it
 Respond in the user's language. Current locale: es
 ```
 
-Error messages the visitor sees come from the widget's `strings` (`errorGeneric`, `errorNetwork`, `errorRateLimit`). The server config also has an `i18n` option, but nothing reads it yet.
+Error messages the visitor sees come from the widget's `strings` (`errorGeneric`, `errorNetwork`, `errorRateLimit`). The server config's `i18n` option is deprecated: the server ignores it and logs a warning when it's set, and it will be removed in a later release.