Add i18next internationalization

- Install i18next and react-i18next with full SSR support
- Configure client-side i18n with browser language detection
- Configure server-side i18n with filesystem backend
- Add improved German translations (idiomatic business German)
- Integrate with Vite via i18next-loader plugin
- Add i18next middleware to Express server
- Update server-side entry to serialize translations for hydration
- Update client-side entry to hydrate with server state
- Translate all Welcome page content with defaultValue pattern
- Document i18n usage and architecture in CLAUDE.md

English text stays inline in components as defaultValue.
Other languages defined in src/locales/*.json files.
Browser automatically detects user's preferred language.
No language flicker due to proper SSR hydration.

Author: Josip-Ledic

package-lock.json

@@ -32,8 +32,14 @@
     "classnames": "^2.5.1",
     "compression": "^1.7.5",
     "express": "^5.0.1",
+    "i18next": "^25.6.0",
+    "i18next-browser-languagedetector": "^8.2.0",
+    "i18next-fs-backend": "^2.6.0",
+    "i18next-http-middleware": "^3.8.1",
+    "i18next-resources-to-backend": "^1.2.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "react-i18next": "^16.2.4",
     "react-router": "^7.5.2",
     "sirv": "^3.0.0"
   },
@@ -70,6 +76,7 @@
     "stylelint-plugin-carbon-tokens": "^3.2.3",
     "stylelint-use-logical-spec": "^5.0.1",
     "vite": "^7.0.0",
+    "vite-plugin-i18next-loader": "^3.1.3",
     "vitest": "^3.0.7"
   },
   "lint-staged": {

package.json

@@ -9,18 +9,37 @@
 import { StrictMode } from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { BrowserRouter } from 'react-router';
+import { I18nextProvider } from 'react-i18next';
 import { Router } from './routes';
 
 // App level imports
 import { ThemeProvider } from './context/ThemeContext';
+import i18n from './i18n.client.js';
+
+// Hydrate i18n with server state to prevent flicker
+const { initialI18nStore, initialLanguage } =
+  window.__INITIAL_I18N_STATE__ || {};
+
+if (initialI18nStore && initialLanguage) {
+  // Add server translations to client instance
+  Object.keys(initialI18nStore).forEach((lng) => {
+    Object.keys(initialI18nStore[lng]).forEach((ns) => {
+      i18n.addResourceBundle(lng, ns, initialI18nStore[lng][ns], true, true);
+    });
+  });
+  // Set the language from server
+  i18n.changeLanguage(initialLanguage);
+}
 
 hydrateRoot(
   document.getElementById('root'),
   <StrictMode>
-    <ThemeProvider>
-      <BrowserRouter>
-        <Router />
-      </BrowserRouter>
-    </ThemeProvider>
+    <I18nextProvider i18n={i18n}>
+      <ThemeProvider>
+        <BrowserRouter>
+          <Router />
+        </BrowserRouter>
+      </ThemeProvider>
+    </I18nextProvider>
   </StrictMode>,
 );

src/entry-client.jsx

@@ -9,29 +9,45 @@
 import { StrictMode } from 'react';
 import { renderToPipeableStream } from 'react-dom/server';
 import { StaticRouter } from 'react-router';
+import { I18nextProvider } from 'react-i18next';
 
 // App level imports
 import { Router } from './routes/index.jsx';
 import { getStatusCodeForPath } from './routes/utils.js';
 
 /**
  * @param {string} url
+ * @param {import('i18next').i18n} i18n
  * @param {import('react-dom/server').RenderToPipeableStreamOptions} [options]
  */
-export function render(_url, options) {
+export function render(_url, i18n, options) {
   const url = `/${_url}`;
   const statusCode = getStatusCodeForPath(url);
 
   const { pipe, abort } = renderToPipeableStream(
     <StrictMode>
-      <StaticRouter location={url}>
-        <Router />
-      </StaticRouter>
+      <I18nextProvider i18n={i18n}>
+        <StaticRouter location={url}>
+          <Router />
+        </StaticRouter>
+      </I18nextProvider>
     </StrictMode>,
     options,
   );
 
-  const head = '<meta name="description" content="Server-side rendered page">';
+  // Serialize i18n state to pass to client
+  const initialI18nStore = {};
+  i18n.languages.forEach((lng) => {
+    initialI18nStore[lng] = i18n.services.resourceStore.data[lng];
+  });
+
+  const initialState = {
+    initialI18nStore,
+    initialLanguage: i18n.language,
+  };
+
+  const head = `<meta name="description" content="Server-side rendered page">
+<script>window.__INITIAL_I18N_STATE__ = ${JSON.stringify(initialState).replace(/</g, '\\u003c')}</script>`;
 
   return { pipe, head, abort, statusCode };
 }

src/entry-server.jsx

@@ -0,0 +1,54 @@
+/**
+ * Copyright IBM Corp. 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import i18next from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+import resourcesToBackend from 'i18next-resources-to-backend';
+
+i18next
+  // Detect user language
+  .use(LanguageDetector)
+  // Pass the i18n instance to react-i18next
+  .use(initReactI18next)
+  // Load translation files dynamically
+  .use(
+    resourcesToBackend((language, namespace) => {
+      // Only load non-English translations from files
+      // English is provided as defaultValue in components
+      if (language === 'en') {
+        return Promise.resolve({});
+      }
+      return import(`./locales/${language}.json`);
+    }),
+  )
+  // Init i18next
+  .init({
+    debug: false,
+    fallbackLng: 'en',
+    supportedLngs: ['en', 'de'],
+
+    // Important for SSR
+    useSuspense: false,
+
+    // Return key if translation missing (useful with defaultValue pattern)
+    returnNull: false,
+    returnEmptyString: false,
+
+    interpolation: {
+      escapeValue: false, // React already escapes values
+    },
+
+    detection: {
+      // Order of language detection
+      order: ['navigator', 'htmlTag'],
+      // Don't cache language in cookies/localStorage for this boilerplate
+      caches: [],
+    },
+  });
+
+export default i18next;

src/i18n.client.js

@@ -0,0 +1,46 @@
+/**
+ * Copyright IBM Corp. 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import i18next from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import Backend from 'i18next-fs-backend';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+i18next
+  // Load translation files from filesystem
+  .use(Backend)
+  // Pass the i18n instance to react-i18next
+  .use(initReactI18next)
+  // Init i18next
+  .init({
+    debug: false,
+    fallbackLng: 'en',
+    supportedLngs: ['en', 'de'],
+    preload: ['en', 'de'], // Preload all languages on server
+
+    // Important for SSR
+    useSuspense: false,
+
+    // Return key if translation missing (useful with defaultValue pattern)
+    returnNull: false,
+    returnEmptyString: false,
+
+    backend: {
+      // Path to translation files
+      loadPath: resolve(__dirname, 'locales/{{lng}}.json'),
+    },
+
+    interpolation: {
+      escapeValue: false, // React already escapes values
+    },
+  });
+
+export default i18next;

src/i18n.server.js

@@ -0,0 +1,27 @@
+{
+  "welcome": {
+    "runTemplate": "↳ Template starten",
+    "nodeRequirement": "Benötigt Node v.20",
+    "whatIsThis": "↳ Worum geht's?",
+    "purpose": {
+      "title": "Verwendungszweck",
+      "description": "Dieses Repository hilft beim Einstieg in das Carbon Design System mit React. Es spart Zeit durch eine fertig konfigurierte Basis für neue Projekte."
+    },
+    "consistency": {
+      "title": "Standards einhalten",
+      "description": "Nutzen Sie dies als Referenz, um IBM Design-Standards einzuhalten. Flexibel anpassbar, dabei konsistent in der User Experience."
+    },
+    "customize": {
+      "title": "Individuell anpassen",
+      "description": "Verstehen Sie dies als Startpunkt und Leitfaden, nicht als starres Framework. Passen Sie es an Ihre Anforderungen an oder nutzen Sie es als Inspiration."
+    },
+    "features": "↳ Features",
+    "dataFetching": {
+      "title": "↳ Beispiel: Daten laden",
+      "description": "Hier wird eine Nachricht dynamisch von einem API-Endpunkt geladen. Das zeigt, wie Sie Daten laden können, während Komponenten sauber und Netzwerklogik getrennt bleiben.",
+      "message": "Nachricht:",
+      "loading": "Lädt...",
+      "failed": "Laden fehlgeschlagen"
+    }
+  }
+}