115 lines
6.1 KiB
Markdown
115 lines
6.1 KiB
Markdown
# @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.
|
||
|