{"id":15238,"library":"storybook-react-i18next","title":"Storybook React i18next Addon","description":"storybook-react-i18next is a Storybook addon that provides seamless integration for react-i18next, enabling developers to test and showcase their localized React components directly within Storybook stories. The current stable version is 10.1.2, which supports Storybook v10, i18next v26, and react-i18next v17. The project maintains an active release cadence, frequently updating to support the latest major versions of its core peer dependencies (Storybook, i18next, and react-i18next). Its primary differentiator is simplifying the process of switching locales within the Storybook UI, allowing designers and developers to easily verify internationalization implementations without complex manual setup per story. It requires pre-existing i18next and react-i18next configurations in the consuming project.","status":"active","version":"10.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/stevensacks/storybook-react-i18next","tags":["javascript","storybook-addons","storybook-i18n","react-i18next","i18next","i18n","localization","internationalization"],"install":[{"cmd":"npm install storybook-react-i18next","lang":"bash","label":"npm"},{"cmd":"yarn add storybook-react-i18next","lang":"bash","label":"yarn"},{"cmd":"pnpm add storybook-react-i18next","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core internationalization library; required for the addon's functionality.","package":"i18next","optional":false},{"reason":"Used by the provided i18next configuration example for detecting user language.","package":"i18next-browser-languagedetector","optional":false},{"reason":"Used by the provided i18next configuration example for loading translation files over HTTP.","package":"i18next-http-backend","optional":false},{"reason":"React binding for i18next; essential for rendering localized React components.","package":"react-i18next","optional":false},{"reason":"The addon integrates with Storybook; specific Storybook major versions are supported.","package":"storybook","optional":false}],"imports":[{"note":"The addon is registered as a string in the 'addons' array within '.storybook/main.ts'.","wrong":"const storybookI18next = require('storybook-react-i18next');","symbol":"storybook-react-i18next","correct":"export default {\n  addons: ['storybook-react-i18next']\n};"},{"note":"The generated i18n instance is typically exported as a default from a custom configuration file (e.g., '.storybook/i18next.ts').","wrong":"import { i18n } from './i18next';","symbol":"i18n (instance)","correct":"import i18n from './i18next';"},{"note":"This is a named export from 'react-i18next', used to initialize i18next with React integration.","wrong":"import initReactI18next from 'react-i18next';","symbol":"initReactI18next","correct":"import { initReactI18next } from 'react-i18next';"},{"note":"The core i18next library is typically imported as a default export for direct configuration.","wrong":"const i18next = require('i18next');","symbol":"i18n (core library)","correct":"import i18next from 'i18next';"}],"quickstart":{"code":"/* .storybook/main.ts */\nimport type { StorybookConfig } from '@storybook/core-common';\n\nconst config: StorybookConfig = {\n  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],\n  addons: [\n    '@storybook/addon-links',\n    '@storybook/addon-essentials',\n    'storybook-react-i18next' // Add this line\n  ],\n  framework: {\n    name: '@storybook/react-vite',\n    options: {},\n  },\n  docs: {\n    autodocs: 'tag',\n  },\n};\n\nexport default config;\n\n\n/* .storybook/i18next.ts */\nimport { initReactI18next } from 'react-i18next';\nimport i18n from 'i18next';\nimport Backend from 'i18next-http-backend';\nimport LanguageDetector from 'i18next-browser-languagedetector';\n\nconst ns = ['common']; // Define your namespaces\nconst supportedLngs = ['en', 'fr', 'ja'];\nconst resources = ns.reduce((acc, n) => {\n  supportedLngs.forEach((lng) => {\n    if (!acc[lng]) acc[lng] = {};\n    acc[lng] = {\n      ...acc[lng],\n      [n]: { /* Your translation keys for namespace 'n' and language 'lng' */\n        'hello': 'Hello from {{name}}',\n        'welcome': 'Welcome to our app'\n      }\n    };\n  });\n  return acc;\n}, {});\n\ni18n.use(initReactI18next)\n  .use(LanguageDetector)\n  .use(Backend) // Optional if you provide resources directly\n  .init({\n    debug: false,\n    lng: 'en',\n    fallbackLng: 'en',\n    defaultNS: 'common',\n    ns,\n    interpolation: { escapeValue: false },\n    react: { useSuspense: false },\n    supportedLngs,\n    resources,\n  });\n\nexport default i18n;\n\n\n/* .storybook/preview.ts */\nimport type { Preview } from '@storybook/react';\nimport i18n from './i18next'; // Import your i18n configuration\n\nconst preview: Preview = {\n  initialGlobals: {\n    locale: 'en',\n    locales: {\n      en: 'English',\n      fr: 'Français',\n      ja: '日本語',\n    },\n  },\n  parameters: {\n    i18n, // Pass your i18n instance here\n  },\n};\n\nexport default preview;\n","lang":"typescript","description":"This quickstart demonstrates how to integrate `storybook-react-i18next` into your Storybook project, including configuring your `main.ts` for addon registration, setting up a basic `i18next.ts` instance with sample resources, and configuring `preview.ts` to enable locale switching in the Storybook toolbar."},"warnings":[{"fix":"Consult the `storybook-react-i18next` README or `package.json` peer dependencies to determine the correct addon version for your Storybook installation, and upgrade or downgrade accordingly.","message":"Major versions of `storybook-react-i18next` are typically tied to specific major versions of Storybook. For example, v10.x of this addon requires Storybook v10.x, while v4.x required Storybook v9.x, and v3.x required Storybook v8.x. Always ensure the addon version matches your Storybook version to avoid conflicts.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always check the addon's peer dependency ranges before upgrading i18n-related packages. Use `npm install --legacy-peer-deps` as a temporary measure if conflicts arise, but the recommended fix is to align versions of all related packages.","message":"This addon has strict peer dependency ranges for `i18next`, `react-i18next`, `i18next-browser-languagedetector`, and `i18next-http-backend`. Upgrading any of these core i18n libraries without also ensuring compatibility with the addon's peer dependency requirements can lead to runtime errors or unexpected behavior.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure you have `i18next`, `react-i18next`, and any necessary plugins (like `i18next-browser-languagedetector` or `i18next-http-backend`) installed and properly configured in your application before attempting to integrate this Storybook addon.","message":"The `storybook-react-i18next` addon assumes that `i18next` and `react-i18next` are already correctly installed, configured, and working within your project. It does not provide the core i18n setup itself, but rather integrates with an existing one.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Follow the detailed usage instructions in the addon's README, paying close attention to the `.storybook/i18next.ts` and `.storybook/preview.ts` setup steps, including `initialGlobals` and `parameters.i18n`.","message":"Configuring `storybook-react-i18next` requires manual creation of an `i18next.ts` (or similar) file within your `.storybook` directory and modifications to your `preview.ts` to pass the i18n instance and define locales. It is not a zero-configuration addon.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"This issue was quickly addressed in subsequent patches. Ensure you are on the latest stable version (currently 10.x) to avoid any legacy peer dependency quirks related to `react`.","message":"Version 4.0.5 briefly added `react` as a peer dependency, then immediately reverted this change within the same version via a subsequent commit. While current versions of the addon do not list `react` as a direct peer dependency, users updating around the v4.0.5 release might have encountered transient `react` peer dependency warnings or errors.","severity":"gotcha","affected_versions":"4.0.5"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install all necessary peer dependencies using `npm install i18next react-i18next i18next-browser-languagedetector i18next-http-backend` and ensure their versions align with the `storybook-react-i18next` peer dependency ranges.","cause":"One of the required peer dependencies (e.g., 'i18next', 'react-i18next') is not installed or does not meet the version requirements.","error":"Error: Cannot find module 'i18next' from '.../node_modules/storybook-react-i18next'"},{"fix":"Verify that your `.storybook/preview.ts` correctly imports your i18n instance and passes it to `parameters.i18n`, and that `initialGlobals.locale` and `initialGlobals.locales` are defined as shown in the quickstart example.","cause":"The `initialGlobals.locales` or `parameters.i18n` are incorrectly configured or missing in `.storybook/preview.ts`.","error":"Locale dropdown not visible in Storybook toolbar or switching locales has no effect."},{"fix":"Double-check the `resources` object and `ns` array in your `.storybook/i18next.ts` to ensure that translation files are correctly loaded and accessible, and that `defaultNS` is set appropriately.","cause":"The i18next configuration in `.storybook/i18next.ts` is not correctly loading translation resources, or the `ns` (namespaces) are misconfigured.","error":"Translation keys are displayed instead of translated text in Storybook stories."},{"fix":"Update your Storybook installation to the version required by the addon (e.g., Storybook v10 for `storybook-react-i18next` v10.x). Review all i18n-related package versions (`i18next`, `react-i18next`, etc.) and ensure they fall within the addon's specified peer dependency ranges. You may temporarily use `npm install --legacy-peer-deps` but strive for full compatibility.","cause":"A conflict exists between the peer dependencies required by `storybook-react-i18next` and other packages in your project, or your Storybook version does not match the addon's requirement.","error":"npm ERR! ERESOLVE unable to resolve dependency tree"}],"ecosystem":"npm"}