Storybook next-intl

https://github.com/stevensacks/storybook-next-intl
Admin
storybook-next-intl is a Storybook addon that integrates next-intl to provide locale switching and...
Tokens:20,479
Snippets:344
Trust Score:7.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Basic Component Setup

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/withNextIntl.md

Example of a component using useTranslations and its corresponding Storybook export.

```typescript
import {useTranslations} from 'next-intl';

const MyComponent = () => {
    const t = useTranslations();
    return <p>{t('greeting')}</p>;
};

export const Default = {
    render: () => <MyComponent />
};
```

--------------------------------

### Install Addon

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/README.md

Install the addon as a development dependency in your project.

```bash
npm i -D storybook-next-intl
```

--------------------------------

### Configure next-intl Formats

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Example implementation of the Formats configuration object.

```typescript
const nextIntl = {
    defaultLocale: 'en',
    messagesByLocale,
    formats: {
        dateTime: {
            short: {
                year: '2-digit',
                month: 'short',
                day: 'numeric'
            }
        },
        number: {
            precise: {
                minimumFractionDigits: 2,
                maximumFractionDigits: 2
            }
        }
    }
};
```

--------------------------------

### Start Combined Development Environment

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Runs the build watcher and the Storybook dev server in parallel.

```bash
npm start
```

--------------------------------

### Configuring Preview Entries

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/preview-annotations.md

Example of how the preview entry point is defined in package.json for automatic loading by Storybook.

```json
{
  "bundler": {
    "previewEntries": ["src/preview.ts"]
  }
}
```

--------------------------------

### Define Development Dependencies

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Example of how the addon is typically added to a project's devDependencies.

```json
{
    "devDependencies": {
        "storybook-next-intl": "^10.1.3"
    }
}
```

--------------------------------

### Configure nextIntl object

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Example configuration object for next-intl settings.

```typescript
const nextIntl = {
    defaultLocale: 'en',
    messagesByLocale,
    formats: {...},
    defaultTranslationValues: {...},
    onError: (error) => console.error(error),
};
```

--------------------------------

### Usage of NextIntlConfig

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Example implementation of the NextIntlConfig object.

```typescript
const nextIntl: NextIntlConfig = {
    defaultLocale: 'en',
    messagesByLocale: {
        en: { greeting: 'Hello' },
        fr: { greeting: 'Bonjour' },
    },
};
```

--------------------------------

### Locale Display Formats

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/QUICK_REFERENCE.md

Examples of simple and rich locale display configurations for the UI.

```typescript
// Simple
locales: {en: 'English'}

// Rich with icons/labels
locales: {
    en: {
        icon: '🇺🇸',
        title: 'English',
        right: 'EN'
    }
}
```

--------------------------------

### Module resolution and import patterns

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

Examples of valid addon registration and preview imports, alongside common invalid import attempts.

```typescript
// ✓ Addon registration (main.ts)
addons: ['storybook-next-intl']

// ✓ Direct import of preview config (rarely used)
import preview from 'storybook-next-intl/preview';

// ✓ Manager auto-loads (manager.ts)
// No explicit import needed

// ✗ Cannot import from index (no exports)
import {something} from 'storybook-next-intl';  // Fails

// ✗ Cannot import decorator directly
import {withNextIntl} from 'storybook-next-intl';  // Fails
```

--------------------------------

### Generate Declaration Files

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Transformation example showing source code and the resulting generated type declaration file.

```typescript
// src/withNextIntl.tsx
export const withNextIntl = (
    StoryFn: StoryFunction<Renderer>,
    context: StoryContext<Renderer>,
) => {
    // ... implementation
};
```

```typescript
// dist/withNextIntl.d.ts
import type {StoryFunction, StoryContext, Renderer} from 'storybook/internal/types';

export const withNextIntl: (
    StoryFn: StoryFunction<Renderer>,
    context: StoryContext<Renderer>,
) => ReactNode | null;
```

--------------------------------

### Usage of InitialGlobals in preview.ts

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Example configuration for initialGlobals within the Storybook preview file.

```typescript
initialGlobals: {
    locale: 'en',
    locales: {
        en: 'English',
        fr: 'Français',
        ja: '日本語'
    }
}
```

--------------------------------

### Run Development Watch Mode

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Starts the tsup build process in watch mode to enable hot reloading during development.

```bash
npm run build:watch
```

--------------------------------

### Identify missing nextIntl parameter

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Example of an incorrect preview configuration missing the required nextIntl parameter.

```typescript
// ✗ Incorrect—missing nextIntl in parameters
const preview: Preview = {
    initialGlobals: {
        locale: 'en',
        locales: {en: 'English'}
    }
    // parameters missing nextIntl
};
```

--------------------------------

### Example of MessagesByLocale structure

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Demonstrates a concrete implementation of the MessagesByLocale type with English and French translations.

```typescript
const messagesByLocale: MessagesByLocale = {
    en: {
        greeting: 'Hello',
        farewell: 'Goodbye',
        items: '{count, plural, =0 {no items} one {# item} other {# items}}'
    },
    fr: {
        greeting: 'Bonjour',
        farewell: 'Au revoir',
        items: '{count, plural, =0 {aucun élément} one {# élément} other {# éléments}}'
    }
};
```

--------------------------------

### Message Format Example

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/QUICK_REFERENCE.md

Standard message structure including support for pluralization.

```typescript
const messages = {
    greeting: 'Hello {name}',
    items: '{count, plural, =0 {no items} one {# item} other {# items}}'
};
```

--------------------------------

### View Code Splitting Output

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Example of how tsup creates shared code chunks when splitting is enabled.

```text
dist/
├── index.js
├── preview.js
├── withNextIntl-XXXXX.js       # Shared code chunk
└── manager.js
```

--------------------------------

### Identify mismatched defaultLocale

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Example of an incorrect configuration where the defaultLocale is not present in messagesByLocale.

```typescript
// ✗ Incorrect—'en' has no messages
const nextIntl = {
    defaultLocale: 'en',
    messagesByLocale: {
        // 'en' missing
        fr: {...}
    }
};
```

--------------------------------

### Pluralization Usage

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/withNextIntl.md

Example of a component utilizing pluralization and the corresponding message definitions.

```typescript
const ComplexComponent = () => {
    const t = useTranslations();
    const [count, setCount] = useState(0);
    
    return (
        <div>
            <button onClick={() => setCount(count + 1)}>
                {t('items', {count})}
            </button>
        </div>
    );
};

export const PluralTest = {
    render: () => <ComplexComponent />
};
```

```typescript
const en = {
    items: '{count, plural, =0 {no items} one {# item} other {# items}}'
};

const fr = {
    items: '{count, plural, =0 {aucun élément} one {# élément} other {# éléments}}'
};
```

--------------------------------

### Hypothetical Direct Import

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

Example of a direct import from the package, which currently fails as the index module does not export members.

```typescript
// Hypothetical—not currently used by any consumers
import {withNextIntl} from 'storybook-next-intl';
```

--------------------------------

### Identify missing locale in messagesByLocale

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Example of an incorrect configuration where a locale defined in locales lacks corresponding messages.

```typescript
// ✗ Incorrect—'es' has no messages
const messagesByLocale = {
    en: {...},
    fr: {...}
};

const locales = {
    en: 'English',
    fr: 'Français',
    es: 'Español'  // Missing in messagesByLocale
};
```

--------------------------------

### Execute build command

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Run the primary build process using npm.

```bash
npm run build
```

--------------------------------

### Build Commands

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/QUICK_REFERENCE.md

Common npm scripts for building, watching, and publishing the project.

```bash
npm run build              # Build for production
npm run build:watch       # Watch and rebuild
npm run build-storybook   # Build static site
npm start                 # Dev: build:watch + storybook
npm run release           # Build and publish to npm
```

--------------------------------

### Configure preview.ts

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/README.md

Set up global locale parameters and initial state for Storybook.

```typescript
import nextIntl from './next-intl';

const preview: Preview = {
    initialGlobals: {
        locale: 'en',
        locales: {
            en: 'English',
            fr: 'Français',
            ja: '日本語',
        },
    },
    parameters: {
      nextIntl,
    },
};

export default preview;
```

```typescript
import nextIntl from './next-intl';

const preview: Preview = {
    initialGlobals: {
        locale: 'en_US',
        locales: {
            en_US: 'English (US)',
            en_GB: 'English (GB)',
            fr_FR: 'Français',
            ja_JP: '日本語',
        },
    },
    parameters: {
      nextIntl,
    },
};

export default preview;
```

```typescript
import nextIntl from './next-intl';

const preview: Preview = {
    initialGlobals: {
        locale: "en",
        locales: {
            en: {icon: '🇺🇸', title: 'English', right: 'EN'},
            fr: {icon: '🇫🇷', title: 'Français', right: 'FR'},
            ja: {icon: '🇯🇵', title: '日本語', right: 'JA'},
        },
    },
    parameters: {
      nextIntl,
    },
};

export default preview;
```

```typescript
import nextIntl from './next-intl';

const preview: Preview = {
    initialGlobals: {
        locale: 'en_US',
        locales: {
            en_US: {title: 'English', right: 'US'},
            en_GB: {title: 'English', right: 'GB'},
            fr_FR: {title: 'Français', right: 'FR'},
            ja_JP: {title: '日本語', right: 'JA'},
        },
    },
    parameters: {
      nextIntl,
    },
};

export default preview;
```

--------------------------------

### Define preview entry point configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

The default export for the preview entry point, containing i18n configuration and decorators.

```typescript
const preview: ProjectAnnotations<Renderer> = {
    ...i18n,
    decorators: [...i18nDecorators, withNextIntl],
};

export default preview;
```

--------------------------------

### Import main entry point

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

Standard import syntax for the main entry point.

```typescript
import 'storybook-next-intl';
```

--------------------------------

### Configure package.json entry points

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Defines the entry points for the tsup bundler to build the addon.

```json
{
    "bundler": {
        "exportEntries": ["src/index.ts"],
        "managerEntries": ["src/manager.ts"],
        "previewEntries": ["src/preview.ts"]
    }
}
```

--------------------------------

### Configure package.json exports

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

Defines the module entry points for index, preview, and manager files.

```json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./preview": {
      "types": "./dist/preview.d.ts",
      "default": "./dist/preview.js"
    },
    "./manager": "./dist/manager.js"
  }
}
```

--------------------------------

### Package.json Bundler Configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

Defines the entry points for the Storybook manager and preview environments.

```json
{
  "bundler": {
    "managerEntries": ["src/manager.ts"],
    "previewEntries": ["src/preview.ts"]
  }
}
```

--------------------------------

### Exporting the Preview Configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/preview-annotations.md

The main preview configuration file that composes decorators from storybook-i18n and the local withNextIntl decorator.

```typescript
import type {Renderer, ProjectAnnotations} from 'storybook/internal/types';
import i18n from 'storybook-i18n/preview';
import {withNextIntl} from './withNextIntl';

const i18nDecorators = i18n.decorators || [];

const preview: ProjectAnnotations<Renderer> = {
    ...i18n,
    decorators: [...i18nDecorators, withNextIntl],
};

export default preview;
```

--------------------------------

### Configure tsup dynamically

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Asynchronously load entry points from package.json to configure the bundler.

```typescript
export default defineConfig(async () => {
    const packageJson = (await import('./package.json', {with: {type: 'json'}}))
        .default;
    
    const {
        bundler: {
            exportEntries = [],
            managerEntries = [],
            previewEntries = [],
            nodeEntries = [],
        },
    } = packageJson;
    
    // Configuration based on entry types...
});
```

--------------------------------

### Configure main.ts

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/README.md

Register the addon in the Storybook configuration file.

```typescript
{
  addons: [
    // other addons...
    'storybook-next-intl',
  ]
}
```

--------------------------------

### import preview from 'storybook-next-intl/preview'

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

The primary entry point for configuring Storybook with next-intl. This exports the ProjectAnnotations required to integrate internationalization into the Storybook preview environment.

```APIDOC
## ESM Import: storybook-next-intl/preview

### Description
Imports the default ProjectAnnotations for Storybook, enabling next-intl support within the Storybook preview.

### Usage
```typescript
import preview from 'storybook-next-intl/preview';
```

### Export Type
- **Default Export**: ProjectAnnotations<Renderer>

### Requirements
- Must be imported as an ESM module (CommonJS `require` is not supported).
```

--------------------------------

### Recommended Addon Order in main.ts

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Recommended placement of the addon within the addons array to ensure proper integration with core Storybook features.

```typescript
addons: [
    '@storybook/addon-links',           // First
    '@storybook/addon-essentials',       // Core features
    '@storybook/addon-interactions',     // Interaction testing
    'storybook-next-intl',               // i18n (after core)
    // Custom addons last
]
```

--------------------------------

### Storybook Preview Configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/withNextIntl.md

Configuring the next-intl decorator within the Storybook preview.ts file.

```typescript
import type {Preview} from '@storybook/react-vite';
import nextIntl from './next-intl';

const preview: Preview = {
    initialGlobals: {
        locale: 'en',
        locales: {
            en: 'English',
            fr: 'Français',
            ja: '日本語'
        }
    },
    parameters: {
        nextIntl
    }
};

export default preview;
```

--------------------------------

### Project File Structure

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/README.md

Visual representation of the project directory layout.

```text
.
├── README.md                      # This file
├── QUICK_REFERENCE.md             # Fast setup and reference
├── INDEX.md                       # Navigation and learning paths
├── TECHNICAL_REFERENCE.md         # Project overview
├── configuration.md               # Setup and configuration
├── types.md                       # Type reference
├── API_EXPORTS.md                 # Public API
├── INTEGRATION_PATTERNS.md        # Architecture and data flow
├── BUILD_AND_DEPLOYMENT.md        # Build system
└── api-reference/
    ├── withNextIntl.md            # Decorator API
    ├── preview-annotations.md     # Preview config
    ├── manager-module.md          # Manager UI
    └── index-module.md            # Index entry
```

--------------------------------

### Configure preview entries

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Define build settings for the story preview iframe.

```typescript
if (previewEntries.length) {
    configs.push({
        ...commonConfig,
        entry: previewEntries,             // ['src/preview.ts']
        platform: 'browser',
        target: 'esnext',
        dts: true,                         // Generate declarations
    });
}
```

--------------------------------

### Development Scripts

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/QUICK_REFERENCE.md

Standard npm scripts for managing the development lifecycle, including linting, building, and running Storybook.

```bash
npm run start              # Dev server + watch build
npm run storybook         # Storybook dev on port 6006
npm run lint              # ESLint check
npm run lint:fix          # ESLint fix
npm run format            # Prettier format
npm run build             # Production build
npm run build-storybook   # Static site
npm run prerelease        # Pre-release checks
npm run release           # Build and publish
```

--------------------------------

### Configure nextIntl Parameter

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Connect configuration to stories via the nextIntl parameter in preview.ts and access it within decorators.

```typescript
// preview.ts
parameters: {
    nextIntl: {
        defaultLocale: 'en',
        messagesByLocale,
        formats: {...},
        onError: (error) => {...}
    }
}
```

```typescript
const {parameters: {nextIntl}} = context;
const {defaultLocale, messagesByLocale} = nextIntl;
```

--------------------------------

### Configure Extended Storybook Preview

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Integrates next-intl with additional Storybook parameters like backgrounds and controls.

```typescript
import type {Preview} from '@storybook/react-vite';
import nextIntl from './next-intl';

const preview: Preview = {
    initialGlobals: {
        locale: 'en',
        locales: {
            en: {icon: '🇺🇸', title: 'English', right: 'EN'},
            fr: {icon: '🇫🇷', title: 'Français', right: 'FR'},
            ja: {icon: '🇯🇵', title: '日本語', right: 'JP'}
        }
    },
    parameters: {
        nextIntl,
        // Other Storybook parameters
        backgrounds: {
            default: 'light'
        },
        controls: {
            matchers: {
                color: /(background|color)$/i,
                date: /Date$/
            }
        }
    }
};

export default preview;
```

--------------------------------

### Clean and Rebuild Project

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Removes the existing distribution directory and triggers a fresh build to resolve interrupted build states.

```bash
rm -rf dist
npm run build
```

--------------------------------

### Execute Release Commands

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Commands for validating and publishing the package to npm.

```bash
npm run prerelease     # Checks before publishing
npm run release        # Builds and publishes
```

--------------------------------

### Configure Package.json for Distribution

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Defines the package entry points, exports, and file inclusion rules for npm publication.

```json
{
    "name": "storybook-next-intl",
    "version": "10.1.3",
    "license": "MIT",
    "type": "module",
    "main": "./dist/index.js",
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
            "default": "./dist/index.js"
        },
        "./preview": {
            "types": "./dist/preview.d.ts",
            "default": "./dist/preview.js"
        },
        "./manager": "./dist/manager.js"
    },
    "files": [
        "dist/**/*",
        "README.md",
        "*.js",
        "*.d.ts"
    ]
}
```

--------------------------------

### Import Preview for CSF Factories

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Importing the preview configuration for use in Component Story Format (CSF) factories.

```typescript
import preview from 'storybook-next-intl/preview';
```

--------------------------------

### Define bundler entries in package.json

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Specify entry points for the bundler within the package.json file.

```json
{
  "bundler": {
    "exportEntries": ["src/index.ts"],
    "managerEntries": ["src/manager.ts"],
    "previewEntries": ["src/preview.ts"]
  }
}
```

--------------------------------

### Import Storybook Preview API

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Importing hooks from the Storybook preview API.

```typescript
import {useGlobals} from 'storybook/preview-api';
```

--------------------------------

### NextIntlConfig

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/QUICK_REFERENCE.md

Configuration object required for setting up the next-intl integration in Storybook.

```APIDOC
## NextIntlConfig

### Description
Required configuration object for the addon.

### Parameters
- **defaultLocale** (string) - Required - The default locale to use.
- **messagesByLocale** (Record<string, any>) - Required - An object mapping locale keys to their respective message objects.
- **formats** (Formats) - Optional - Custom formats for next-intl.
- **defaultTranslationValues** (Record) - Optional - Default values for translations.
- **onError** ((error) => void) - Optional - Error handling callback.
- **getMessageFallback** ((obj) => string) - Optional - Fallback function for missing messages.
```

--------------------------------

### Storybook Globals Configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Sets the initial locale and available options within the preview.ts configuration.

```typescript
// preview.ts configuration
initialGlobals: {
    locale: 'en',           // Initial value
    locales: {              // Available options
        en: 'English',
        fr: 'Français'
    }
}
```

--------------------------------

### Package Exports Configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

Defines the package entry points in package.json for ESM resolution.

```json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  }
}
```

--------------------------------

### Configure initialGlobals in preview.ts

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/manager-module.md

Define the default locale and available locales to populate the toolbar dropdown.

```typescript
// In preview.ts
initialGlobals: {
    locale: 'en',
    locales: {
        en: 'English',
        fr: 'Français',
        ja: '日本語'
    }
}
```

--------------------------------

### Global Update Flow

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Illustrates the communication flow from the manager UI to the preview layer.

```text
// storybook-i18n/manager (re-exported)
user clicks dropdown
    ↓
manager calls setGlobals({locale: 'fr'})
```

--------------------------------

### Index module build outputs

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

The generated build artifacts for the index module, which remain minimal to satisfy module resolution.

```javascript
export default {};
```

```typescript
export default {};
```

--------------------------------

### Configure Custom Formats

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Define custom date, time, number, and list formatting rules within the configuration.

```typescript
const nextIntl = {
    defaultLocale: 'en',
    messagesByLocale,
    formats: {
        dateTime: {
            short: {
                year: '2-digit',
                month: 'short',
                day: 'numeric'
            },
            long: {
                weekday: 'long',
                year: 'numeric',
                month: 'long',
                day: 'numeric'
            }
        },
        number: {
            precise: {
                minimumFractionDigits: 2,
                maximumFractionDigits: 2
            }
        },
        list: {
            enumeration: {
                type: 'conjunction',
                style: 'long'
            }
        }
    }
};
```

--------------------------------

### Define Peer Dependencies

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Specifies the required versions of next-intl and Storybook for consumers of the addon.

```json
{
    "peerDependencies": {
        "next-intl": "^3 || ^4",
        "storybook": "^9.0.0 || ^10.0.0"
    }
}
```

--------------------------------

### Configure Release Scripts in package.json

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Defines the prerelease and release scripts for automated changelog and publishing workflows.

```json
{
    "scripts": {
        "prerelease": "zx scripts/prepublish-checks.js",
        "release": "npm run build && auto shipit"
    }
}
```

--------------------------------

### View Published File Structure

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Represents the directory structure of the package as it appears after publication.

```text
storybook-next-intl/
├── dist/                  # All built artifacts
│   ├── *.js
│   ├── *.d.ts
│   └── *.map
├── README.md             # Documentation
├── package.json
└── LICENSE
```

--------------------------------

### ESM Import Patterns

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

Demonstrates supported ESM import syntax versus unsupported CommonJS require syntax.

```typescript
// ✓ Supported
import preview from 'storybook-next-intl/preview';

// ✗ Not supported
const preview = require('storybook-next-intl/preview');  // CommonJS

// ✓ Supported (ESM with TypeScript)
import type {ProjectAnnotations} from 'storybook/internal/types';
```

--------------------------------

### Manager Entry Point

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

The manager entry point is used to register the addon within the Storybook manager frame. It is automatically loaded by Storybook when imported.

```APIDOC
## Manager Entry Point

### Description
Registers the addon's UI components, toolbar, and state management within the Storybook manager frame.

### Usage
```typescript
import 'storybook-next-intl/manager';
```
```

--------------------------------

### Addon Pattern Registration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

Registers the addon in the Storybook main configuration file.

```typescript
// main.ts
addons: ['storybook-next-intl']
```

--------------------------------

### Module Import Resolution

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

Demonstrates how the package is resolved when imported.

```typescript
import 'storybook-next-intl'     // Resolves to dist/index.js
```

--------------------------------

### withNextIntl(StoryFn, context)

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/withNextIntl.md

A decorator function that wraps a Storybook story with the NextIntlClientProvider context, using locale information from Storybook globals or story parameters.

```APIDOC
## withNextIntl(StoryFn, context)

### Description
Wraps a Storybook story with the `NextIntlClientProvider` to provide internationalization support. It resolves the active locale from Storybook globals or story parameters and injects the appropriate messages.

### Parameters
- **StoryFn** (PartialStoryFn<Renderer>) - Required - The story function to render.
- **context** (StoryContext<Renderer>) - Required - The Storybook context containing parameters and globals.

### Configuration Requirements
The `context.parameters.nextIntl` object must be provided with the following fields:
- **defaultLocale** (string) - Required - The default locale identifier.
- **messagesByLocale** (Record<string, any>) - Required - Mapping of locale identifiers to message objects.

### Return Type
- **ReactNode | null** - The story component wrapped in the provider, or the original story if configuration is missing.
```

--------------------------------

### Advanced Configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/withNextIntl.md

Defining custom error handling, fallbacks, formats, and default translation values.

```typescript
const nextIntl = {
    defaultLocale: 'en',
    messagesByLocale,
    onError: (error) => {
        console.error('Translation error:', error);
    },
    getMessageFallback: ({namespace, key}) => `${namespace}.${key}`,
    formats: {
        dateTime: {
            short: {
                year: '2-digit',
                month: 'short',
                day: 'numeric'
            }
        }
    },
    defaultTranslationValues: {
        company: 'Acme Corp'
    }
};
```

--------------------------------

### Configure next-intl.ts

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/README.md

Define the locale configuration and message mappings for Storybook.

```typescript
import en from '../src/messages/en.json';
import fr from '../src/messages/fr.json';
import ja from '../src/messages/ja.json';

const messagesByLocale: Record<string, any> = {en, fr, ja};

const nextIntl = {
  defaultLocale: 'en',
  messagesByLocale,
};

export default nextIntl;
```

```typescript
const nextIntl = {
  defaultLocale: 'en',
  messagesByLocale,
  formats: {/* your settings */},
  defaultTranslationValues: {/* your settings */},
  onError: (error) => console.error(error),
  getMessageFallback: ({namespace, key}) => `${namespace}.${key}`,
};
```

--------------------------------

### Define Locale Display Options

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/manager-module.md

Configure locales using either simple strings or rich objects with icons and labels for the toolbar UI.

```typescript
// Simple string format
locales: {
    en: 'English'
}

// Rich object format
locales: {
    en: {
        icon: '🇺🇸',      // Left icon (optional)
        title: 'English',   // Main text (required)
        right: 'EN'        // Right label (optional)
    }
}
```

--------------------------------

### Generate Portable Stories Type Declarations

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Entry point for generating type declarations for portable stories in Storybook.

```typescript
// dist/preview.d.ts
import type {ProjectAnnotations} from 'storybook/internal/types';
export default preview: ProjectAnnotations<Renderer>;
```

--------------------------------

### Configure manager entries

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Define build settings for the Storybook UI manager frame.

```typescript
if (managerEntries.length) {
    configs.push({
        ...commonConfig,
        entry: managerEntries,             // ['src/manager.ts']
        platform: 'browser',
        target: 'esnext',
    });
}
```

--------------------------------

### View dist/ Directory Structure

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Visual representation of the files generated in the distribution directory.

```text
dist/
├── index.js                    # Main entry (empty export)
├── index.d.ts                  # Type declarations for index
├── preview.js                  # Preview iframe code
├── preview.d.ts                # Type declarations for preview
├── manager.js                  # Manager frame code
├── withNextIntl.js             # Chunked code splitting
├── withNextIntl.d.ts           # Type declarations
├── storybook-i18n.*.js         # Dependencies (re-exports)
└── *.map                       # Source maps
```

--------------------------------

### Tsup Build Configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

Configures the index module as an export entry for the build process.

```typescript
if (exportEntries.length) {
    configs.push({
        ...commonConfig,
        entry: exportEntries,              // ['src/index.ts']
        platform: 'browser',
        target: 'esnext',
        dts: true,                         // Generate declarations
    });
}
```

--------------------------------

### Preview Type Declaration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

Type declaration for the preview entry point, importing necessary Storybook types.

```typescript
import type {Renderer, ProjectAnnotations} from 'storybook/internal/types';
import type i18n from 'storybook-i18n/preview';

declare const preview: ProjectAnnotations<Renderer>;
export default preview;
```

--------------------------------

### Package Distribution Configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

Defines the files included in the npm package via the package.json files array.

```json
{
  "files": [
    "dist/**/*",
    "README.md",
    "*.js",
    "*.d.ts"
  ]
}
```

--------------------------------

### Implement getMessageFallback

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Shows how to use the MessageFallback type within the next-intl configuration.

```typescript
const nextIntl = {
    defaultLocale: 'en',
    messagesByLocale,
    getMessageFallback: ({namespace, key}: MessageFallback) => {
        return `${namespace}.${key}`;
    }
};
```

--------------------------------

### Document Bundler Entry Types

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Explanatory comments within the configuration file detailing the purpose of different entry types.

```typescript
/*
 export entries are package-root exports that users or Storybook resolve
 directly from the addon package...
*/

/*
 manager entries are entries meant to be loaded into the manager UI...
*/

/*
 preview entries are entries meant to be loaded into the preview iframe...
*/
```

--------------------------------

### Simple Message Formatting

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/QUICK_REFERENCE.md

Basic key-value pair for static string translation.

```typescript
{greeting: 'Hello'}
// t('greeting') → 'Hello'
```

--------------------------------

### Implement Error Handling in withNextIntl

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Wrap the provider in a try-catch block to handle missing parameters or locale errors gracefully.

```typescript
export const withNextIntl = (StoryFn, context) => {
    try {
        const [{locale}] = useGlobals();
        // ...
        return <NextIntlClientProvider ...>{StoryFn(context)}</NextIntlClientProvider>;
    } catch (error) {
        // React's built-in error handling applies
        console.error(error);
        return StoryFn(context);  // Fallback: render without provider
    }
};
```

--------------------------------

### Decorator Execution Wrapping

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Visual representation of the decorator chain execution order.

```text
(decorator1) =>
  (decorator2) =>
    (decorator3: withNextIntl) =>
      (StoryFn) =>
        {wrapped story}
```

--------------------------------

### Implement withNextIntl Decorator

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

The decorator reads the current locale from Storybook globals and wraps the story in a NextIntlClientProvider.

```typescript
export const withNextIntl = (StoryFn, context) => {
    const [{locale}] = useGlobals();           // Read 'fr' from global
    const {parameters: {nextIntl}} = context;  // Get config
    
    const currentLocale = locale || nextIntl.defaultLocale;  // 'fr'
    const currentMessages = nextIntl.messagesByLocale[currentLocale];  // French messages
    
    return (
        <NextIntlClientProvider
            {...nextIntl}
            locale={currentLocale}
            messages={currentMessages}
        >
            {StoryFn(context)}  // Render story inside provider
        </NextIntlClientProvider>
    );
};
```

--------------------------------

### Integrate withNextIntl in preview.ts

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/withNextIntl.md

Adds the decorator to the Storybook decorator chain to ensure it executes after base i18n decorators.

```typescript
const preview: ProjectAnnotations<Renderer> = {
    ...i18n,
    decorators: [...i18nDecorators, withNextIntl],
};
```

--------------------------------

### Decorator Composition in preview.ts

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Assembles i18n decorators with the next-intl provider to ensure correct execution order.

```typescript
const i18nDecorators = i18n.decorators || [];  // From storybook-i18n

const preview: ProjectAnnotations<Renderer> = {
    ...i18n,
    decorators: [...i18nDecorators, withNextIntl],
};
```

--------------------------------

### Configure Error Handling and Fallbacks

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Define custom error handling and message fallback logic within the nextIntl configuration object.

```typescript
const nextIntl = {
    defaultLocale: 'en',
    messagesByLocale,
    onError: (error) => {
        // Catches formatting errors
        console.error(error);
    },
    getMessageFallback: ({key}) => {
        // Returns string for missing messages
        return `[${key}]`;
    }
};
```

--------------------------------

### Direct Import Pattern Registration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

Manually imports and registers the decorator in the preview configuration.

```typescript
// preview.ts
import {withNextIntl} from 'storybook-next-intl';

const preview: Preview = {
    decorators: [withNextIntl]
};
```

--------------------------------

### Parameter Resolution Logic

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Demonstrates the internal logic for resolving the current locale by prioritizing parameters over globals.

```typescript
const [{locale}] = useGlobals();                    // Global
const {parameters: {locale: paramLocale}} = context; // Parameter

// Parameter takes precedence if set
const currentLocale = locale || defaultLocale;
// Actually uses: paramLocale || locale || defaultLocale
```

--------------------------------

### Compose Custom Decorators

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Composing custom decorators within the Storybook preview configuration while maintaining automatic i18n context.

```typescript
const preview: Preview = {
    decorators: [
        customDecorator1,
        customDecorator2,
        // withNextIntl applied automatically
    ]
};
```

--------------------------------

### Import React Types

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Standard React type imports for component definitions.

```typescript
import type {ReactNode} from 'react';
import type {FC} from 'react';
```

--------------------------------

### Define Locale Configurations

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/TECHNICAL_REFERENCE.md

Locales can be defined as simple key-value pairs or as rich objects containing icons and labels.

```typescript
// Simple string format
locales: {
  en: 'English',
  fr: 'Français',
  ja: '日本語'
}

// Rich object format with icons/labels
locales: {
  en: {icon: '🇺🇸', title: 'English', right: 'EN'},
  fr: {icon: '🇫🇷', title: 'Français', right: 'FR'}
}
```

--------------------------------

### Configure TypeScript (tsconfig.json)

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Compiler settings optimized for modern module resolution and strict type checking.

```typescript
{
    "compilerOptions": {
        "target": "esnext",        // Output modern JavaScript
        "module": "preserve",      // Preserve import/export syntax (tsup handles bundling)
        "jsx": "react",            // React JSX transform
        "strict": true,            // Strict type checking
        "moduleResolution": "bundler",  // Modern resolution algorithm
        "isolatedModules": true,   // Each file compilable in isolation
        "verbatimModuleSyntax": true    // Preserve exact import syntax
    },
    "include": ["src/**/*", "tsup.config.ts"],
    "rootDir": "."
}
```

--------------------------------

### Message Formatting

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/QUICK_REFERENCE.md

Format dates or other types using predefined configuration formats.

```typescript
{date: '{date, date, long}'}
// Requires: formats.dateTime.long defined in config
// t('date', {date: new Date()}) → 'August 26, 2026'
```

--------------------------------

### Define withNextIntl function signature

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/withNextIntl.md

The decorator accepts a Story function and the Storybook context, returning a ReactNode.

```typescript
export const withNextIntl = (
    StoryFn: StoryFunction<Renderer>,
    context: StoryContext<Renderer>,
) => ReactNode | null
```

--------------------------------

### withNextIntl Decorator

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

The withNextIntl decorator is used to wrap stories with the next-intl provider. While registered automatically, it can be imported for custom composition.

```APIDOC
## withNextIntl Decorator

### Description
A decorator function that wraps a Storybook story with the next-intl provider context.

### Signature
`withNextIntl(StoryFn: StoryFunction<Renderer>, context: StoryContext<Renderer>): ReactNode | null`

### Parameters
- **StoryFn** (PartialStoryFn<Renderer>) - The story function to render.
- **context** (StoryContext<Renderer>) - The current Storybook context.

### Returns
- **ReactNode | null** - The rendered story wrapped in the provider.
```

--------------------------------

### Import Messages from JSON Files

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Use standard imports to load message files into the messagesByLocale object.

```typescript
import en from '../src/messages/en.json';
import fr from '../src/messages/fr.json';

const messagesByLocale: Record<string, any> = {en, fr};
```

--------------------------------

### Handle IntlError in configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Demonstrates using the onError callback to handle translation errors.

```typescript
const nextIntl = {
    defaultLocale: 'en',
    messagesByLocale,
    onError: (error: IntlError) => {
        console.error('Translation error:', error);
    }
};
```

--------------------------------

### Index Type Declaration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

Default type declaration for the index entry point.

```typescript
declare const _default: {};
export default _default;
```

--------------------------------

### Configure Error Handling

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Implement custom error handling and fallback logic for missing translation keys.

```typescript
const nextIntl = {
    defaultLocale: 'en',
    messagesByLocale,
    onError: (error) => {
        console.error('Translation error:', error);
    },
    getMessageFallback: ({namespace, key}) => {
        return `${namespace}.${key}`;
    }
};
```

--------------------------------

### Define Formats Type

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Structure for configuring date/time, number, and list formatting options.

```typescript
type Formats = {
    dateTime?: Record<string, DateTimeFormatOptions>;
    number?: Record<string, NumberFormatOptions>;
    list?: Record<string, ListFormatOptions>;
}
```

--------------------------------

### Define NextIntlConfig type

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

The expected shape for the nextIntl parameter in the addon configuration.

```typescript
type NextIntlConfig = {
    defaultLocale: string;
    messagesByLocale: Record<string, Record<string, any>>;
    formats?: Formats;
    defaultTranslationValues?: Record<string, any>;
    onError?: (error: IntlError) => void;
    getMessageFallback?: (fallback: MessageFallback) => string;
    timeZone?: string;
    now?: Date;
}
```

--------------------------------

### Future extensibility pattern

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

Shows how the empty export pattern allows for future addition of named exports without breaking existing implementations.

```typescript
// Hypothetical future version
export {withNextIntl} from './withNextIntl';
export type {NextIntlConfig} from './types';
```

```typescript
import {withNextIntl} from 'storybook-next-intl';
```

--------------------------------

### Define ProjectAnnotations type

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Configuration object for global story annotations including decorators and parameters.

```typescript
type ProjectAnnotations<TRenderer> = {
    decorators?: DecoratorFunction<TRenderer>[];
    parameters?: Parameters;
    globalTypes?: GlobalTypes;
    args?: Record<string, any>;
    [key: string]: any;
}
```

```typescript
const preview: ProjectAnnotations<Renderer> = {
    ...i18n,
    decorators: [...i18nDecorators, withNextIntl],
};
```

--------------------------------

### Manager Module Dependency Chain

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/manager-module.md

Visual representation of the dependency hierarchy between the manager entry, storybook-i18n, and core Storybook APIs.

```text
storybook-next-intl/manager.ts
    ↓ re-exports
storybook-i18n/manager
    ↓ depends on
storybook (manager APIs)
    ↓ depends on
react (UI rendering)
```

--------------------------------

### withNextIntl Decorator Signature

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/QUICK_REFERENCE.md

The decorator function signature used to wrap stories in the NextIntlClientProvider.

```typescript
function withNextIntl(
    StoryFn: PartialStoryFn<Renderer>,
    context: StoryContext<Renderer>
): ReactNode | null
```

--------------------------------

### Configure Default Translation Values

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Set global default values for placeholders used across multiple translation strings.

```typescript
const nextIntl = {
    defaultLocale: 'en',
    messagesByLocale,
    defaultTranslationValues: {
        company: 'Acme Corp',
        year: 2024
    }
};
```

```typescript
const en = {
    copyright: '© {year} {company}. All rights reserved.'
};
```

```typescript
t('copyright')  // © 2024 Acme Corp. All rights reserved.
```

--------------------------------

### Define external packages

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

List packages that should not be bundled, as they are provided by the runtime.

```typescript
external: ['react', 'react-dom', '@storybook/icons'],
```

--------------------------------

### Define common tsup configuration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Set shared options applied to all entry types, including format and external dependencies.

```typescript
const commonConfig: Options = {
    clean: false,
    format: ['esm'],
    treeshake: true,
    splitting: true,
    external: ['react', 'react-dom', '@storybook/icons'],
};
```

--------------------------------

### Clear Storybook Cache

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/BUILD_AND_DEPLOYMENT.md

Removes the local cache directory to force the development server to pick up recent changes.

```bash
rm -rf node_modules/.cache
```

--------------------------------

### Set TypeScript Compiler Options

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Strict compiler settings for the project to ensure type safety and explicit annotations.

```json
{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexAccess": true,
        "noImplicitOverride": true,
        "noImplicitAny": true,
        "isolatedModules": true,
        "verbatimModuleSyntax": true,
        "jsx": "react"
    }
}
```

--------------------------------

### Access locale via useGlobals

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/withNextIntl.md

Uses the Storybook preview API to provide reactive access to the current locale selection from the toolbar.

```typescript
import {useGlobals} from 'storybook/preview-api';

const [{locale}] = useGlobals();
```

--------------------------------

### Structure Message Sources

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/TECHNICAL_REFERENCE.md

Messages are organized by locale within a Record object passed to the configuration.

```typescript
const messagesByLocale: Record<string, any> = {
  en: { /* messages */ },
  fr: { /* messages */ },
  ja: { /* messages */ }
};
```

--------------------------------

### Index Module Type Declaration

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

The generated type declaration file for the index module.

```typescript
// dist/index.d.ts
export default {};
```

--------------------------------

### Define InitialGlobals type

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

The structure for the initialGlobals configuration.

```typescript
type InitialGlobals = {
    locale: string;
    locales: Record<string, LocaleDisplay>;
}
```

--------------------------------

### Decorator Chain Pattern

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/preview-annotations.md

Standard pattern for extending existing Storybook decorators while maintaining compatibility with empty arrays.

```typescript
const baseDecorators = someSource.decorators || [];
const allDecorators = [...baseDecorators, newDecorator];
```

--------------------------------

### useGlobals

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

A React hook that provides reactive access to Storybook globals and a function to update them.

```APIDOC
## useGlobals

### Description
React hook that provides reactive access to Storybook globals and a function to update them.

### Signature
`function useGlobals(): [globals: Record<string, any>, updateGlobals: (newGlobals: Record<string, any>) => void]`

### Return Value
- `[0]` (Record<string, any>) - Current globals object
- `[1]` (Function) - Function to update globals
```

--------------------------------

### Use Translations Hook

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/QUICK_REFERENCE.md

Implement translation hooks for basic strings, values, pluralization, and ICU formatting.

```typescript
import {useTranslations} from 'next-intl';

const t = useTranslations();

// Basic translation
t('key')

// With values
t('greeting', {name: 'John'})

// With pluralization
t('items', {count: 5})

// With ICU MessageFormat
const msg = '{count, plural, =0 {no items} one {# item} other {# items}}';
t('items', {count: 0})
```

--------------------------------

### Global Subscription in Decorator

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Uses the useGlobals hook to subscribe to locale changes within the decorator.

```typescript
// withNextIntl decorator
const [{locale}] = useGlobals();  // Subscribes to changes
// Re-runs when locale global changes
```

--------------------------------

### Define Inline Message Objects

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/configuration.md

Define translation messages directly within the configuration file instead of importing external JSON files.

```typescript
const messagesByLocale: Record<string, any> = {
    en: {
        greeting: 'Hello',
        world: 'World'
    },
    fr: {
        greeting: 'Bonjour',
        world: 'Monde'
    }
};
```

--------------------------------

### Access globals with useGlobals

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Shows how to read the current locale global value within an addon.

```typescript
const [{locale}] = useGlobals();
// Reads the current 'locale' global value
```

--------------------------------

### Re-exporting Manager Module

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/manager-module.md

Exports all functionality from the upstream storybook-i18n manager package.

```typescript
export * from 'storybook-i18n/manager';
```

```typescript
export * from 'storybook-i18n/manager';
```

--------------------------------

### Define NextIntlClientProviderProps interface

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Props interface for the NextIntlClientProvider component. Most properties are optional, with locale, messages, and children being required.

```typescript
type NextIntlClientProviderProps = {
    locale: string;
    messages: Record<string, any>;
    defaultLocale?: string;
    messagesByLocale?: Record<string, Record<string, any>>;
    formats?: Formats;
    defaultTranslationValues?: Record<string, any>;
    onError?: (error: IntlError) => void;
    getMessageFallback?: (fallback: MessageFallback) => string;
    timeZone?: string;
    now?: Date;
    children: ReactNode;
}
```

--------------------------------

### Compose Custom Decorator

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/API_EXPORTS.md

Advanced usage for composing decorators by importing from internal paths. Note that this approach is not guaranteed to be stable across versions.

```typescript
import preview from 'storybook-next-intl/preview';
import {withNextIntl} from 'storybook-next-intl/dist/preview.js';  // Internal path

export const MyPreview = {
    ...preview,
    decorators: [
        customDecorator,
        withNextIntl,
        ...preview.decorators
    ]
};
```

--------------------------------

### Define useGlobals hook signature

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Provides the type signature for the useGlobals hook from storybook/preview-api.

```typescript
function useGlobals(): [globals: Record<string, any>, updateGlobals: (newGlobals: Record<string, any>) => void]
```

--------------------------------

### Empty Export Pattern

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/api-reference/index-module.md

The explicit empty object export used by the module.

```typescript
export default {};
```

--------------------------------

### Higher-Order Function Pattern for withNextIntl

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/INTEGRATION_PATTERNS.md

Defines the decorator as a higher-order function to wrap the story component with the next-intl provider.

```typescript
const withNextIntl: Decorator<Renderer> = (StoryFn, context) => {
    // Read from context
    // Prepare provider props
    // Return wrapped component
    return <Provider>{StoryFn(context)}</Provider>;
};
```

--------------------------------

### Import Storybook Types

Source: https://github.com/stevensacks/storybook-next-intl/blob/main/_autodocs/types.md

Required type imports for Storybook internal types.

```typescript
import type {Renderer, ProjectAnnotations} from 'storybook/internal/types';
import type {
    PartialStoryFn as StoryFunction,
    StoryContext,
} from 'storybook/internal/types';
```
Tokens:
Raw