Storybook React i18next Addon

Common errors

• Error: Cannot find module 'i18next' from '.../node_modules/storybook-react-i18next'

  cause 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.

  cause 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.

  cause 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

  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.
  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.

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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`.
• gotcha 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.
  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`.

Install

• npm install storybook-react-i18next npm
• yarn add storybook-react-i18next yarn
• pnpm add storybook-react-i18next pnpm

Imports

• storybook-react-i18next
  wrong:

  const storybookI18next = require('storybook-react-i18next');

  correct:

  export default {
    addons: ['storybook-react-i18next']
  };

  The addon is registered as a string in the 'addons' array within '.storybook/main.ts'.
• i18n (instance)
  wrong:

  import { i18n } from './i18next';

  correct:

  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
  wrong:

  import initReactI18next from 'react-i18next';

  correct:

  import { initReactI18next } from 'react-i18next';

  This is a named export from 'react-i18next', used to initialize i18next with React integration.
• i18n (core library)
  wrong:

  const i18next = require('i18next');

  correct:

  import i18next from 'i18next';

  The core i18next library is typically imported as a default export for direct configuration.

Quickstart

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;