# @suaveplan/i18n-shared - Shared runtime atoms for the @suaveplan/i18n family — locale constants, BCP-47 map, RTL set, locale descriptors, interpolation defaults, the I18N_CODES error registry, and the I18nError class. Consumed by every i18n leaf package (parser, formatters, detector, backends) and re-exported by the slim core.

## Summary

Shared runtime atoms for the entire `@suaveplan/i18n*` package family —
locale constants, BCP-47 normalisation map, RTL set, locale
descriptors, interpolation defaults, the `I18N_CODES` error registry,
and the `I18nError` base class. Consumed by every i18n leaf package
(parser, formatters, detector, backends) and re-exported by the slim
core (Wave 6).

<!-- begin:auto-docs -->
## Documentation tree

- [interpolation-defaults](./src/constants/interpolation-defaults.md) — `DEFAULT_INTERPOLATION` is the canonical default configuration for the ICU interpolation engine that ships with `@suave…
- [locale-bcp47-map](./src/constants/locale-bcp47-map.md) — `LOCALE_BCP47_MAP` is the single source of truth for normalising the short and mixed-case locale identifiers consumers…
- [locale-descriptors](./src/constants/locale-descriptors.md) — These three exports together define the built-in supported-locale inventory for the Suaveplan i18n family. `DEFAULT_LOC…
- [rtl-locales](./src/constants/rtl-locales.md) — `RTL_LOCALES` and `RTL_LOCALE_LIST` are the canonical inventory of ISO 639-1 language codes whose primary script render…
- [error-codes](./src/errors/error-codes.md) — `I18N_CODES` is the single, frozen registry of every fully-qualified error code that any package in the `@suaveplan/i18…
- [i18n-error](./src/errors/i18n-error.md) — `I18nError` is the single base class every package in the `@suaveplan/i18n*` family throws. It extends `SuaveplanError<…
- [testing](./src/testing/conformance.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [conformance](./src/testing/conformance.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [conformance](./src/testing/conformance.md) — <!-- begin:auto-docs --> _(no submodules)_- [conformance](./src/testing/conformance.md) — <!-- begin:auto-docs --> _(no submodules)_- [conformance](./src/testing/conformance.md) — <!-- begin:auto-docs --> _(no submodules)_- [conformance](./src/testing/conformance.md) — <!-- begin:auto-docs --> _(no submodules)_
## Why this exists

The 14-package i18n modular split needs one home for the runtime
atoms every leaf consumes. Constants and the `I18nError` class can
not live in `@suaveplan/types` (zero runtime) and they can not stay
in `@suaveplan/i18n` core because formatters / backends / detectors
would each need a dependency on the core, which causes a cycle the
moment the slim core re-exports any of them. The clean answer is a
universal leaf runtime package — this one.

## Install

```bash
bun add @suaveplan/i18n-shared
```

## Quick Start

```ts
import {
    DEFAULT_INTERPOLATION,
    I18N_CODES,
    I18nError,
    LOCALE_BCP47_MAP,
    RTL_LOCALES,
} from "@suaveplan/i18n-shared";

// BCP-47 normalisation
const tag = LOCALE_BCP47_MAP["en"]; // "en-GB"

// RTL detection
const isRtl = RTL_LOCALES.has("ar"); // true

// Error throwing
throw new I18nError(I18N_CODES.MISSING_KEY, "checkout.button");
```

## Modules

| Subpath | Description |
|---|---|
| `@suaveplan/i18n-shared` | Root barrel — every constant + `I18nError` + codes |
| `@suaveplan/i18n-shared/constants` | All constants (zero error-class dep) |
| `@suaveplan/i18n-shared/constants/locale-bcp47-map` | `LOCALE_BCP47_MAP` only |
| `@suaveplan/i18n-shared/constants/rtl-locales` | `RTL_LOCALES` and `RTL_LOCALE_LIST` only |
| `@suaveplan/i18n-shared/constants/locale-descriptors` | `LOCALE_DESCRIPTORS`, `DEFAULT_LOCALES`, `DefaultLocale` only |
| `@suaveplan/i18n-shared/constants/interpolation-defaults` | `DEFAULT_INTERPOLATION` only |
| `@suaveplan/i18n-shared/errors` | `I18N_CODES`, `I18nError`, `I18nErrorCode` |
| `@suaveplan/i18n-shared/testing` | `runBackendConformance` — shared `Backend` contract harness used by every `@suaveplan/i18n-backend-*` package |

## Modules Documentation

- [locale-bcp47-map.md](src/constants/locale-bcp47-map.md) — short / mixed-case → canonical BCP-47 tag
- [rtl-locales.md](src/constants/rtl-locales.md) — `RTL_LOCALES` + `RTL_LOCALE_LIST`
- [locale-descriptors.md](src/constants/locale-descriptors.md) — `LOCALE_DESCRIPTORS`, `DEFAULT_LOCALES`, `DefaultLocale`
- [interpolation-defaults.md](src/constants/interpolation-defaults.md) — `DEFAULT_INTERPOLATION`
- [error-codes.md](src/errors/error-codes.md) — `I18N_CODES`, `I18nErrorCode`
- [i18n-error.md](src/errors/i18n-error.md) — `I18nError` base class
- [conformance.md](src/testing/conformance.md) — `runBackendConformance` — shared backend conformance harness

## Public Surface (snapshot)

| Export | Kind | Origin |
|---|---|---|
| `LOCALE_BCP47_MAP` | const | `constants/locale-bcp47-map.ts` |
| `RTL_LOCALES` | const | `constants/rtl-locales.ts` |
| `RTL_LOCALE_LIST` | const | `constants/rtl-locales.ts` |
| `LOCALE_DESCRIPTORS` | const | `constants/locale-descriptors.ts` |
| `DEFAULT_LOCALES` | const | `constants/locale-descriptors.ts` |
| `DefaultLocale` | type | `constants/locale-descriptors.ts` |
| `DEFAULT_INTERPOLATION` | const | `constants/interpolation-defaults.ts` |
| `I18N_CODES` | const | `errors/error-codes.ts` |
| `I18nErrorCode` | type | `errors/error-codes.ts` |
| `I18nCode` | type alias | `errors/error-codes.ts` |
| `I18nError` | class | `errors/i18n-error.ts` |

## Versioning

This package is part of the i18n modular-split rollout. Stays at
`0.1.0` until the slim core (Wave 6) cuts the family `1.0.0`
release. The `I18N_CODES` registry is append-only across the wave —
existing codes never get removed or renamed.

## Wave 1 Scope

This package is Wave 1b of the 14-package i18n modular split. It
ships pure additions only — `packages/i18n/i18n/src/` retains its
copies of these atoms until Wave 6 deletes them. Both copies coexist
during Waves 2–5; downstream consumers continue to import from the
monolith and observe no behaviour change.