first commit
This commit is contained in:
114
docs/localization/i18n/i18n-shared/README.md
Normal file
114
docs/localization/i18n/i18n-shared/README.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# @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.
|
||||
|
||||
Reference in New Issue
Block a user