Initial Commit

packages/localization/i18n/i18n-shared/src/constants/locale-descriptors.md

@@ -0,0 +1,91 @@
+# `LOCALE_DESCRIPTORS`, `DEFAULT_LOCALES`, `DefaultLocale`
+
+## Purpose
+
+These three exports together define the built-in supported-locale
+inventory for the Suaveplan i18n family. `DEFAULT_LOCALES` is the
+ordered tuple of locale codes that ship in every bundle by default;
+`DefaultLocale` is the string-literal union derived from that tuple
+(consumers can use it as a strongly-typed parameter); and
+`LOCALE_DESCRIPTORS` is the per-locale display-metadata table
+(English `name`, locale-native `nativeName`, text `direction`). The
+data lets a UI render a locale picker, a sitemap generator emit
+`<link hreflang>` tags, and the locale detector resolve fallback
+chains — all without round-tripping through external locale data.
+
+## Features
+
+- 16 default locales: `en`, `es`, `fr`, `de`, `cy`, `zh`, `ar`, `ru`,
+  `pl`, `ja`, `ko`, `pt`, `it`, `nl`, `he`, `fa`
+- Cross-checked invariant — every `DEFAULT_LOCALES` entry has a
+  descriptor; every descriptor's `direction` agrees with the
+  locale's membership in `RTL_LOCALES`
+- Static, tree-shakeable, zero-dependency
+
+## Usage: Basic Example
+
+```ts
+import { LOCALE_DESCRIPTORS } from "@suaveplan/i18n-shared";
+
+const meta = LOCALE_DESCRIPTORS["ar"];
+console.log(meta.name);       // "Arabic"
+console.log(meta.nativeName); // "العربية"
+console.log(meta.direction);  // "rtl"
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    DEFAULT_LOCALES,
+    type DefaultLocale,
+    LOCALE_DESCRIPTORS,
+} from "@suaveplan/i18n-shared/constants/locale-descriptors";
+
+// Render a typed locale picker
+function buildPicker(): Array<{ value: DefaultLocale; label: string }> {
+    return DEFAULT_LOCALES.map((code) => {
+        const descriptor = LOCALE_DESCRIPTORS[code];
+        return {
+            value: code,
+            label: `${descriptor?.nativeName ?? code} (${descriptor?.name ?? "?"})`,
+        };
+    });
+}
+
+// DefaultLocale narrows at the API boundary
+function setLocale(locale: DefaultLocale): void {
+    document.documentElement.lang = locale;
+    const direction = LOCALE_DESCRIPTORS[locale]?.direction ?? "ltr";
+    document.documentElement.dir = direction;
+}
+```
+
+## API Reference
+
+### `DEFAULT_LOCALES: readonly [...]`
+
+Ordered tuple of 16 ISO 639-1 codes. Iteration order is the canonical
+default order used when the locale detector exhausts its
+preference-list inputs.
+
+### `DefaultLocale`
+
+Type alias equal to `(typeof DEFAULT_LOCALES)[number]`. Use as a
+parameter type to constrain a function to the built-in locale set.
+
+### `LOCALE_DESCRIPTORS: Record<string, { name; nativeName; direction }>`
+
+Per-locale display metadata. Lookup is O(1). Returns `undefined` for
+unknown codes — consumers handle the miss.
+
+## Implementation Notes
+
+- The table is keyed on the short ISO 639-1 code (NOT the canonical
+  BCP-47 tag) so consumers using `LOCALE_BCP47_MAP` for runtime
+  formatting can still read the descriptor with the un-mapped key.
+- `nativeName` values use the script's actual code points (e.g.
+  `"العربية"`, `"中文"`) — file encoding MUST be UTF-8.
+- The list is intentionally small — adding a locale is a deliberate
+  product decision, and the cross-file invariant test catches drift
+  with `RTL_LOCALES`.