# Nimbus

To install dependencies:

```bash
pnpm install
```

To build:

```bash
pnpm run build
```

> **Important:** This package includes generated i18n files (`*.messages.ts` and
> `intl/*.ts`) that are **not tracked in git**. After cloning or switching
> branches, you must run `pnpm build` or `pnpm extract-intl` from the repository
> root to generate these files. Without them, TypeScript compilation and
> Storybook will fail.

## Internationalization (i18n) Development

### Workflow

1. **Create `.i18n.ts` source file** in the component's directory:
   - Example: `/components/alert/alert.i18n.ts`
   - Use the [i18n template](../../docs/component-templates/i18n.template.md) as
     a starting point
   - Message IDs must follow: `Nimbus.{ComponentName}.{messageKey}`
   - Be specific with descriptions - they help translators understand context
   - **Note:** This file is for extraction only - components don't import it at
     runtime

2. **Use messages in your component**:
   - Import the compiled message strings and the hook:
     ```typescript
     import { useLocalizedStringFormatter } from "@/hooks";
     import { {componentName}MessagesStrings } from "./{component-name}.messages";
     ```
   - Use the hook in your component:
     ```typescript
     const msg = useLocalizedStringFormatter({componentName}MessagesStrings);
     ```
   - Call `msg.format("key")` for simple strings
   - Call `msg.format("key", { variableName: value })` for variable messages
   - See [i18n guidelines](../../docs/file-type-guidelines/i18n.md) for detailed
     usage patterns

3. **Extract and compile messages**:
   - Run `pnpm extract-intl` from the project root
   - This command performs two operations:
     1. **Extracts** messages from all `.i18n.ts` files →
        `packages/i18n/data/core.json`
     2. **Compiles** messages into `*.messages.ts` dictionaries (runs full build
        pipeline)
   - Messages are translated via Transifex workflow
   - **Note:** The i18n build also runs automatically during `pnpm build`

4. **Test in Storybook** to ensure locale is working as expected:
   - Use `NimbusI18nProvider` in stories to test different locales
   - Set `locale` prop to verify translations appear correctly

### Dependencies

**Message extraction and runtime:**

- **Extraction**: `.i18n.ts` source files are plain TypeScript objects extracted
  by a custom script (`packages/i18n/scripts/extract-messages.ts`).
- **Runtime**: Components use compiled `.messages.ts` dictionaries with
  `LocalizedStringDictionary` from `@internationalized/string` and
  `react-aria-components` for message retrieval.

### Quick Reference

**Adding a new message:**

1. Create/update `.i18n.ts` file in component directory
2. Run `pnpm extract-intl` (extracts + compiles in one step)
3. Use in component: `msg.format("key")` or
   `msg.format("key", { variable: value })`

**Updating existing messages:**

- Edit `.i18n.ts` file
- Run `pnpm extract-intl` to re-extract and compile
- Changes reflect immediately in components

**Testing locale changes:**

- Use `NimbusI18nProvider` in Storybook stories
- Set `locale` prop to test different languages (e.g., `locale="de"`)
- Verify messages appear correctly for each locale

**Troubleshooting:**

- **Module not found errors after clone/branch switch?** Generated i18n files
  are not tracked in git. Run `pnpm build` or `pnpm extract-intl` from the
  repository root to regenerate them.
- **Empty string returned?** Check that message key matches the ID (not the
  object key from `.i18n.ts`)
  - Example: `id: "Nimbus.Alert.dismiss"` → use `msg.format("dismiss")`, not the
    object key
- **TypeScript error about missing messages?** Run `pnpm extract-intl` to
  regenerate `*.messages.ts` files
- **Messages not updating?** Ensure `*.messages.ts` files are generated by
  running `pnpm extract-intl`
- **Wrong locale showing?** Verify `NimbusI18nProvider` wraps your component
  with correct `locale` prop

### Extracting Messages

```bash
pnpm extract-intl
```

This command performs two operations:

1. **Extracts** translation messages from all `.i18n.ts` files and saves them to
   `packages/i18n/data/core.json`
2. **Compiles** the extracted messages into component-level message dictionaries
   in `packages/nimbus/src/components/*/intl/` and `*.messages.ts` files

**Note:** The i18n package also builds automatically during `pnpm build`.

> 📦 Translation data is organized in the
> [`@commercetools/nimbus-i18n`](../i18n/README.md) package.