# Nimbus

To install dependencies:

```bash
pnpm install
```

To build:

```bash
pnpm run build
```

## 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 { componentMessagesStrings } from "./component.messages";
     ```
   - Use the hook in your component:
     ```typescript
     const msg = useLocalizedStringFormatter(componentMessagesStrings);
     ```
   - 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

**`react-intl` is a dev dependency only** - it is not required at runtime:

- **In `devDependencies`**: Needed for `.i18n.ts` source files which use
  `defineMessages` from `react-intl`. The `@formatjs/cli extract` tool expects
  this format to extract messages.
- **Not in `peerDependencies`**: Consumers do not need to install `react-intl`.
  Components use compiled `.messages.ts` dictionaries at runtime, not the
  `.i18n.ts` source files.
- **Runtime**: Components use `LocalizedStringDictionary` from
  `@internationalized/string` and `react-aria-components` for message retrieval,
  not `react-intl`.

### 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:**

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