first commit

docs/localization/i18n/locale-data/src/languages/languages.data.md

@@ -0,0 +1,78 @@
+# languages.data
+
+## Purpose
+
+Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: `LANGUAGES_DATA`
+(130+ language entries) and `RTL_LANGUAGES` (the list of right-to-left script codes). This file is
+intentionally separated from the lookup logic in `languages.ts` to keep both files under the
+300-line hard limit. The data serves as the single source of truth for all language lookups and
+RTL detection in the `@suaveplan/locale-data` package.
+
+## Features
+
+- **130+ ISO 639-1 language entries** — covers the full set of two-letter language codes in the
+  ISO standard, from Afar (`aa`) to Zulu (`zu`).
+- **Two fields per entry** — `name` (English name) and `native` (name in the language's own script,
+  e.g. `"Deutsch"` for German, `"العربية"` for Arabic).
+- **`RTL_LANGUAGES` constant** — readonly array of 15 ISO 639-1 codes whose primary script is
+  right-to-left: `ar`, `az`, `ba`, `dv`, `fa`, `he`, `iu`, `ks`, `ku`, `ps`, `sd`, `sr`, `tg`,
+  `ur`, `yi`.
+- **Typed as `Record<string, LanguageItem>`** — ensures each entry satisfies the `LanguageItem`
+  shape defined in the types module.
+- **Unicode-safe** — native names include characters from Arabic, Hebrew, Cyrillic, Devanagari,
+  Georgian, Thai, Chinese, Japanese, Korean, and other scripts.
+
+## Usage: Basic Example
+
+```ts
+// Imported indirectly via the languages module:
+import { getLanguages } from "@suaveplan/locale-data/languages";
+const all = getLanguages(); // returns LANGUAGES_DATA reference
+console.log(all["ja"].name);   // "Japanese"
+console.log(all["ja"].native); // "日本語"
+```
+
+## Usage: Advanced Example
+
+```ts
+import { getRtlLanguages, isRtlLanguage } from "@suaveplan/locale-data/languages";
+
+// Get all RTL codes
+const rtlCodes = getRtlLanguages();
+console.log(rtlCodes); // ["ar", "az", "ba", "dv", "fa", "he", "iu", "ks", "ku", "ps", "sd", "sr", "tg", "ur", "yi"]
+
+// BCP-47 tag detection
+console.log(isRtlLanguage("ar-EG")); // true  (Arabic, Egypt)
+console.log(isRtlLanguage("zh-TW")); // false (Traditional Chinese)
+```
+
+## API Reference
+
+### `LANGUAGES_DATA`
+
+```ts
+const LANGUAGES_DATA: Record<string, LanguageItem>
+```
+
+A frozen constant record mapping ISO 639-1 two-letter codes to `LanguageItem` objects.
+Do not import or mutate this directly from outside the languages module — use the public lookup
+functions instead.
+
+### `RTL_LANGUAGES`
+
+```ts
+const RTL_LANGUAGES: readonly string[]
+```
+
+A readonly array of ISO 639-1 codes for right-to-left scripts. Used by `getRtlLanguages()` and
+`isRtlLanguage()`. Do not mutate.
+
+## Implementation Notes
+
+The data file is excluded from test coverage measurement because it contains no executable logic —
+only plain `export const` declarations. The RTL language list was derived from the reference
+implementation at `packages/universal/utils/src/languages/languages.ts` in the reference project.
+The list includes `az` (Azerbaijani) and `sr` (Serbian) because both languages historically use
+RTL scripts in some contexts, consistent with the reference data. The `isRtlLanguage` function
+imports `RTL_LANGUAGES` as a readonly array and uses `Array.prototype.includes` for O(n) membership
+testing — with only 15 RTL codes, this is negligible overhead compared to a `Set` construction.