feat: add i18n support to storybook

Author: florianduros

.storybook/languageAddon.tsx

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+import { Addon, types, useGlobals } from "storybook/manager-api";
+import { WithTooltip, IconButton, TooltipLinkList } from "storybook/internal/components";
+import React, { useEffect } from "react";
+import { GlobeIcon } from "@storybook/icons";
+
+/**
+ * Returns the title of a language in the user's locale.
+ */
+function languageTitle(language: string): string {
+    return new Intl.DisplayNames([language], { type: "language", style: "short" }).of(language) || language;
+}
+
+export const languageAddon: Addon = {
+    title: "Language Selector",
+    type: types.TOOL,
+    render: ({ active }) => {
+        const [globals, updateGlobals] = useGlobals();
+        const selectedLanguage = globals.language || "en";
+
+        const [languages, setLanguages] = React.useState<string[]>([]);
+        useEffect(() => {
+            const loadLanguages = async () => {
+                // We can't import `shared/i18n.tsx` directly here.
+                // The storybook addon doesn't seem to benefit the webpack config of storybook and we can't resolve the alias in i18n.tsx.
+                const json = await import("../webapp/i18n/languages.json");
+                const languages = Object.keys(json).filter((lang) => lang !== "default");
+                setLanguages(languages);
+            };
+
+            loadLanguages();
+        }, []);
+
+        return (
+            <WithTooltip
+                placement="top"
+                trigger="click"
+                closeOnOutsideClick
+                tooltip={({ onHide }) => {
+                    return (
+                        <TooltipLinkList
+                            links={languages.map((language) => ({
+                                id: language,
+                                title: languageTitle(language),
+                                active: selectedLanguage === language,
+                                onClick: async () => {
+                                    // Update the global state with the selected language
+                                    updateGlobals({ language });
+                                    onHide();
+                                },
+                            }))}
+                        />
+                    );
+                }}
+            >
+                <IconButton title="Language">
+                    <GlobeIcon />
+                    {languageTitle(selectedLanguage)}
+                </IconButton>
+            </WithTooltip>
+        );
+    },
+};

.storybook/main.ts

@@ -1,7 +1,14 @@
 import type { StorybookConfig } from "@storybook/react-vite";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { nodePolyfills } from "vite-plugin-node-polyfills";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 const config: StorybookConfig = {
     stories: ["../src/shared-components/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+    staticDirs: ["../webapp"],
     addons: [
         "@storybook/addon-docs",
         "@storybook/addon-designs",
@@ -41,5 +48,20 @@ const config: StorybookConfig = {
     typescript: {
         reactDocgen: "react-docgen-typescript",
     },
+    async viteFinal(config) {
+        // Merge custom configuration into the default config
+        const { mergeConfig } = await import("vite");
+
+        return mergeConfig(config, {
+            resolve: {
+                alias: {
+                    // Alias used by i18n.tsx
+                    $webapp: path.resolve(__dirname, "../webapp"),
+                },
+            },
+            // Needed for counterpart to work
+            plugins: [nodePolyfills({ include: ["process", "util"] })],
+        });
+    },
 };
 export default config;

.storybook/manager.js

@@ -1,6 +1,11 @@
+import React from "react";
+
 import { addons } from "storybook/manager-api";
 import ElementTheme from "./ElementTheme";
+import { languageAddon } from "./languageAddon";
 
 addons.setConfig({
     theme: ElementTheme,
 });
+
+addons.register("elementhq/language", () => addons.add("language", languageAddon));

.storybook/preview.tsx

@@ -1,13 +1,15 @@
 import type { ArgTypes, Preview, Decorator } from "@storybook/react-vite";
+import { addons } from "storybook/preview-api";
 
 import "../res/css/shared.pcss";
 import "./preview.css";
 import React, { useLayoutEffect } from "react";
+import { FORCE_RE_RENDER } from "storybook/internal/core-events";
+import { setLanguage } from "../src/shared-components/i18n";
 
 export const globalTypes = {
     theme: {
         name: "Theme",
-        defaultValue: "system",
         description: "Global theme for components",
         toolbar: {
             icon: "circlehollow",
@@ -21,6 +23,14 @@ export const globalTypes = {
             ],
         },
     },
+    language: {
+        name: "Language",
+        description: "Global language for components",
+    },
+    initialGlobals: {
+        theme: "system",
+        language: "en",
+    },
 } satisfies ArgTypes;
 
 const allThemesClasses = globalTypes.theme.toolbar.items.map(({ value }) => `cpd-theme-${value}`);
@@ -48,9 +58,33 @@ const withThemeProvider: Decorator = (Story, context) => {
     );
 };
 
+const LanguageSwitcher: React.FC<{
+    language: string;
+}> = ({ language }) => {
+    useLayoutEffect(() => {
+        const changeLanguage = async (language: string) => {
+            await setLanguage(language);
+            // Force the component to re-render to apply the new language
+            addons.getChannel().emit(FORCE_RE_RENDER);
+        };
+        changeLanguage(language);
+    }, [language]);
+
+    return null;
+};
+
+export const withLanguageProvider: Decorator = (Story, context) => {
+    return (
+        <>
+            <LanguageSwitcher language={context.globals.language} />
+            <Story />
+        </>
+    );
+};
+
 const preview: Preview = {
     tags: ["autodocs"],
-    decorators: [withThemeProvider],
+    decorators: [withThemeProvider, withLanguageProvider],
 };
 
 export default preview;

package.json

@@ -192,6 +192,7 @@
         "@storybook/addon-designs": "^10.0.1",
         "@storybook/addon-docs": "^9.0.12",
         "@storybook/addon-styling-webpack": "^2.0.0",
+        "@storybook/icons": "^1.4.0",
         "@storybook/react-vite": "^9.0.15",
         "@stylistic/eslint-plugin": "^4.0.0",
         "@svgr/webpack": "^8.0.0",
@@ -303,6 +304,7 @@
         "typescript": "5.8.3",
         "util": "^0.12.5",
         "vite": "^7.0.1",
+        "vite-plugin-node-polyfills": "^0.24.0",
         "web-streams-polyfill": "^4.0.0",
         "webpack": "^5.89.0",
         "webpack-bundle-analyzer": "^4.8.0",