Registry / testing / storybook-react-i18next

storybook-react-i18next

JSON →
library10.1.2jsnpmunverified

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.

npm install storybook-react-i18next
INSTALL
IMPORT
SIG · STORYBOOK-REACT-I1
S
storybook-react-i18next
testingjavascriptv10.1.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

storybook-react-i18next
export default { addons: ['storybook-react-i18next'] };
const storybookI18next = require('storybook-react-i18next');
The addon is registered as a string in the 'addons' array within '.storybook/main.ts'.
i18n (instance)
import i18n from './i18next';
import { i18n } from './i18next';
The generated i18n instance is typically exported as a default from a custom configuration file (e.g., '.storybook/i18next.ts').
initReactI18next
import { initReactI18next } from 'react-i18next';
import initReactI18next from 'react-i18next';
This is a named export from 'react-i18next', used to initialize i18next with React integration.
i18n (core library)
import i18next from 'i18next';
const i18next = require('i18next');
The core i18next library is typically imported as a default export for direct configuration.

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.

/* .storybook/main.ts */ import type { StorybookConfig } from '@storybook/core-common'; const config: StorybookConfig = { stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'], addons: [ '@storybook/addon-links', '@storybook/addon-essentials', 'storybook-react-i18next' // Add this line ], framework: { name: '@storybook/react-vite', options: {}, }, docs: { autodocs: 'tag', }, }; export default config; /* .storybook/i18next.ts */ import { initReactI18next } from 'react-i18next'; import i18n from 'i18next'; import Backend from 'i18next-http-backend'; import LanguageDetector from 'i18next-browser-languagedetector'; const ns = ['common']; // Define your namespaces const supportedLngs = ['en', 'fr', 'ja']; const resources = ns.reduce((acc, n) => { supportedLngs.forEach((lng) => { if (!acc[lng]) acc[lng] = {}; acc[lng] = { ...acc[lng], [n]: { /* Your translation keys for namespace 'n' and language 'lng' */ 'hello': 'Hello from {{name}}', 'welcome': 'Welcome to our app' } }; }); return acc; }, {}); i18n.use(initReactI18next) .use(LanguageDetector) .use(Backend) // Optional if you provide resources directly .init({ debug: false, lng: 'en', fallbackLng: 'en', defaultNS: 'common', ns, interpolation: { escapeValue: false }, react: { useSuspense: false }, supportedLngs, resources, }); export default i18n; /* .storybook/preview.ts */ import type { Preview } from '@storybook/react'; import i18n from './i18next'; // Import your i18n configuration const preview: Preview = { initialGlobals: { locale: 'en', locales: { en: 'English', fr: 'Français', ja: '日本語', }, }, parameters: { i18n, // Pass your i18n instance here }, }; export default preview;
Debug
Known issues
breakingMajor 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.
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.
affects: >=3.0.0
breakingThis 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.
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.
affects: >=3.0.0
gotchaThe `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.
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.
affects: >=3.0.0
gotchaConfiguring `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.
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`.
affects: >=3.0.0
gotchaVersion 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.
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`.
affects: 4.0.5
Errors
Common errors & fixes
Error: Cannot find module 'i18next' from '.../node_modules/storybook-react-i18next'
One of the required peer dependencies (e.g., 'i18next', 'react-i18next') is not installed or does not meet the version requirements.
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.
Locale dropdown not visible in Storybook toolbar or switching locales has no effect.
The `initialGlobals.locales` or `parameters.i18n` are incorrectly configured or missing in `.storybook/preview.ts`.
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.
Translation keys are displayed instead of translated text in Storybook stories.
The i18next configuration in `.storybook/i18next.ts` is not correctly loading translation resources, or the `ns` (namespaces) are misconfigured.
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.
npm ERR! ERESOLVE unable to resolve dependency tree
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.
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.
Upgrade
Version history
10.1.2latest on npm
Audit
Dependencies
i18nextrequiredCore internationalization library; required for the addon's functionality.
i18next-browser-languagedetectorrequiredUsed by the provided i18next configuration example for detecting user language.
i18next-http-backendrequiredUsed by the provided i18next configuration example for loading translation files over HTTP.
react-i18nextrequiredReact binding for i18next; essential for rendering localized React components.
storybookrequiredThe addon integrates with Storybook; specific Storybook major versions are supported.
Agent activity
2 hits · last 30 days
node
2
Resources
storybook-react-i18next — npm install storybook-react-i18next · libregistry