# `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`.