From f2b30ad0c7ea25517d0280d60ed2960d58de8c7a Mon Sep 17 00:00:00 2001
From: anurag629 <78868769+anurag629@users.noreply.github.com>
Date: Sat, 17 Oct 2026 11:25:41 +0530
Subject: [PATCH] docs: say which languages the widget ships

---
 README.md                                     |  2 +-
 website/src/content/docs/server/setup.mdx     |  2 +-
 .../src/content/docs/widget/configuration.mdx |  2 +-
 website/src/content/docs/widget/i18n.mdx      | 57 +++++++------------
 4 files changed, 25 insertions(+), 38 deletions(-)

diff --git a/README.md b/README.md
index 6762afb..76bafe5 100644
--- a/README.md
+++ b/README.md
@@ -57,7 +57,7 @@ That's it. Your site now has an AI chat widget.
 - **Knowledge base** - Feed text chunks or FAQ pairs for context-aware responses.
 - **Conversation persistence** - localStorage on client, pluggable stores on server.
 - **Analytics** - Track conversations, messages, and lead captures.
-- **i18n** - 8 built-in locales, fully customizable strings.
+- **i18n** - Replace any widget string, and the model replies in the visitor's language.
 - **Deployable anywhere** - Express, Vercel, Cloudflare Workers adapters included.
 - **Customizable** - Theme, branding, position, welcome messages, callbacks.
 
diff --git a/website/src/content/docs/server/setup.mdx b/website/src/content/docs/server/setup.mdx
index b4d7888..8cbf0f9 100644
--- a/website/src/content/docs/server/setup.mdx
+++ b/website/src/content/docs/server/setup.mdx
@@ -65,7 +65,7 @@ const handler = chatcopsMiddleware({
   // Optional: CORS origin
   cors: '*',
 
-  // Optional: i18n
+  // Optional: i18n (accepted, but the server doesn't read it yet)
   i18n: {
     defaultLocale: 'en',
     locales: { /* custom strings */ },
diff --git a/website/src/content/docs/widget/configuration.mdx b/website/src/content/docs/widget/configuration.mdx
index 3350613..58166ea 100644
--- a/website/src/content/docs/widget/configuration.mdx
+++ b/website/src/content/docs/widget/configuration.mdx
@@ -150,7 +150,7 @@ interface WidgetConfig {
   maxMessages?: number;       // Max messages to persist, default: 50
   pageContext?: boolean;       // Send page URL/title, default: true
   autoOpen?: boolean | number; // Popup mode only. true = immediate, number = delay in ms
-  locale?: string;            // 'en' | 'es' | 'hi' | 'fr' | 'de' | 'ja' | 'zh' | 'ar'
+  locale?: string;            // Sent to the server with each message. Only English strings are built in
   strings?: Partial<WidgetLocaleStrings>; // Custom i18n overrides
 
   // Callbacks
diff --git a/website/src/content/docs/widget/i18n.mdx b/website/src/content/docs/widget/i18n.mdx
index e73894d..1f0ffd6 100644
--- a/website/src/content/docs/widget/i18n.mdx
+++ b/website/src/content/docs/widget/i18n.mdx
@@ -3,10 +3,12 @@ title: Internationalization
 description: Localize the ChatCops widget for different languages.
 ---
 
-ChatCops includes 8 built-in locales with full UI string translations.
+The widget's own text ships in English. For another language, pass your translations in `strings`. Built-in translations for more languages are tracked in [#55](https://github.com/codercops/chatcops/issues/55).
 
 ## Setting a Locale
 
+The widget sends `locale` with every message, and the server asks the model to reply in that language.
+
 ### Via script tag
 
 ```html
@@ -17,31 +19,37 @@ ChatCops includes 8 built-in locales with full UI string translations.
 ></script>
 ```
 
+There's no script tag attribute for `strings`, so the widget's buttons and placeholders stay in English here. Use `ChatCops.init` to translate them.
+
 ### Programmatically
 
 ```typescript
 ChatCops.init({
   apiUrl: '/api/chat',
-  locale: 'fr',
+  locale: 'es',
+  strings: {
+    welcomeMessage: '¿En qué puedo ayudarte hoy?',
+    greetingWithName: '¡Hola, {name}!',
+    inputPlaceholder: 'Escribe un mensaje...',
+    sendButton: 'Enviar',
+    closeButton: 'Cerrar',
+  },
 });
 ```
 
+Any string you leave out stays in English.
+
 ## Available Locales
 
 | Code | Language |
 |------|----------|
 | `en` | English (default) |
-| `es` | Spanish |
-| `hi` | Hindi |
-| `fr` | French |
-| `de` | German |
-| `ja` | Japanese |
-| `zh` | Chinese |
-| `ar` | Arabic |
+
+Any other `locale` uses the English strings, with your `strings` on top.
 
 ## Locale Strings
 
-Each locale provides translations for:
+`strings` accepts any of these keys:
 
 ```typescript
 interface LocaleStrings {
@@ -74,31 +82,10 @@ interface LocaleStrings {
 
 ## Server-Side i18n
 
-The server also supports i18n for error messages and system prompts:
+The server doesn't translate anything itself. When a request has a `locale`, it adds this line to the system prompt:
 
-```typescript
-chatcopsMiddleware({
-  provider: { type: 'claude', apiKey: '...' },
-  systemPrompt: '...',
-  i18n: {
-    defaultLocale: 'en',
-    locales: {
-      es: {
-        welcomeMessage: 'Hola! Como puedo ayudarte?',
-        inputPlaceholder: 'Escribe un mensaje...',
-        sendButton: 'Enviar',
-        closeButton: 'Cerrar',
-        errorGeneric: 'Algo salio mal. Intentalo de nuevo.',
-        errorNetwork: 'Error de conexion.',
-        errorRateLimit: 'Demasiados mensajes. Espera un momento.',
-        typingIndicator: 'Escribiendo...',
-        poweredBy: 'Desarrollado por',
-        newConversation: 'Nueva conversacion',
-        welcomeBubbleDefault: 'Necesitas ayuda?',
-      },
-    },
-  },
-});
+```text
+Respond in the user's language. Current locale: es
 ```
 
-The widget sends its current `locale` with each request, and the server uses it to select the appropriate strings.
+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.