skills/plugins/document-navigator/docs/localization/i18n/i18n-shared/README.md

@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).

Documentation tree

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

- [conformance](./src/testing/conformance.md) — _(no submodules)_- [conformance](./src/testing/conformance.md) — _(no submodules)_- [conformance](./src/testing/conformance.md) — _(no submodules)_- [conformance](./src/testing/conformance.md) — _(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

bun add @suaveplan/i18n-shared

Quick Start

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 — short / mixed-case → canonical BCP-47 tag
• rtl-locales.md — RTL_LOCALES + RTL_LOCALE_LIST
• locale-descriptors.md — LOCALE_DESCRIPTORS, DEFAULT_LOCALES, DefaultLocale
• interpolation-defaults.md — DEFAULT_INTERPOLATION
• error-codes.md — I18N_CODES, I18nErrorCode
• i18n-error.md — I18nError base class
• 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.