react-native-ensys-camera-x 1.0.7

package/src/locales.ts

@@ -0,0 +1,381 @@
+/**
+ * locales.ts — the plugin's locale engine.
+ *
+ * This file is the ONLY place that knows how to interpret a language identifier.
+ * It is deliberately data-driven rather than language-driven: there is no list of
+ * "supported languages" anywhere in the plugin and no `switch (language)` branch.
+ * Anything that is a well-formed BCP-47 tag works, including every language the
+ * host app happens to support today and every one it adds later.
+ *
+ * What that means in practice:
+ *
+ *   - Right-to-left is derived from the tag's *script*, either written explicitly
+ *     (`ku-Arab`) or implied by the language subtag (`ar`, `fa`, `he`, `ur`, …).
+ *     Adding Hebrew or Urdu to the host app needs no plugin change.
+ *   - Region and script are peeled off one at a time to build a fallback chain,
+ *     so `zh-Hans-CN` finds a `zh-Hans` bundle, and `pt-BR` finds a `pt` bundle.
+ *   - Legacy and macro tags are folded onto their modern equivalents, because
+ *     host i18n libraries disagree about them (`zh-CN` vs `zh-Hans`, `iw` vs `he`).
+ *
+ * The engine is pure and side-effect free. `localization.ts` owns the state.
+ */
+
+/** Canonical shape of a parsed language identifier. */
+export interface ParsedLocale {
+  /** Lowercase ISO-639 language subtag, e.g. `zh`. Empty for an unusable tag. */
+  language: string;
+  /** Title-case ISO-15924 script subtag, e.g. `Hans`. Empty when absent. */
+  script: string;
+  /** Uppercase ISO-3166 region subtag, e.g. `CN`. Empty when absent. */
+  region: string;
+  /** The normalized tag these three parts recombine into, e.g. `zh-Hans-CN`. */
+  tag: string;
+}
+
+/** The locale used whenever the host has not told us anything else. */
+export const DEFAULT_LOCALE = 'en';
+
+/**
+ * ISO-15924 scripts written right-to-left.
+ *
+ * This is the primary RTL signal. A tag that names its script (`ku-Arab`,
+ * `pa-Arab`, `sr-Hebr`) is classified from this set alone, which is why the
+ * plugin needs no per-language RTL table for scripts it has never seen.
+ */
+export const RTL_SCRIPTS: ReadonlySet<string> = new Set([
+  'Adlm', // Adlam
+  'Arab', // Arabic
+  'Aran', // Nastaliq variant of Arabic
+  'Armi', // Imperial Aramaic
+  'Avst', // Avestan
+  'Cprt', // Cypriot
+  'Egyp', // Egyptian hieroglyphs
+  'Hatr', // Hatran
+  'Hebr', // Hebrew
+  'Hung', // Old Hungarian
+  'Khar', // Kharoshthi
+  'Lydi', // Lydian
+  'Mand', // Mandaic
+  'Mani', // Manichaean
+  'Mend', // Mende Kikakui
+  'Merc', // Meroitic cursive
+  'Mero', // Meroitic hieroglyphs
+  'Narb', // Old North Arabian
+  'Nbat', // Nabataean
+  'Nkoo', // N'Ko
+  'Orkh', // Old Turkic
+  'Palm', // Palmyrene
+  'Phli', // Inscriptional Pahlavi
+  'Phlp', // Psalter Pahlavi
+  'Phnx', // Phoenician
+  'Prti', // Inscriptional Parthian
+  'Rohg', // Hanifi Rohingya
+  'Samr', // Samaritan
+  'Sarb', // Old South Arabian
+  'Sogd', // Sogdian
+  'Sogo', // Old Sogdian
+  'Syrc', // Syriac
+  'Thaa', // Thaana
+  'Yezi', // Yezidi
+]);
+
+/**
+ * Languages whose default script is right-to-left.
+ *
+ * Used only when the tag does not name a script — `fa` has to resolve to RTL
+ * without the host having to write `fa-Arab`. Each entry is the *language*
+ * subtag; regions never change direction, so `ar-EG` and `ar` behave the same.
+ *
+ * Of the languages a typical host app ships, Arabic (`ar`) and Persian/Farsi
+ * (`fa`) are the RTL ones. The rest of this set costs nothing and means Hebrew,
+ * Urdu, Kurdish and friends work the day the host adds them.
+ */
+export const RTL_LANGUAGES: ReadonlySet<string> = new Set([
+  'ar', // Arabic
+  'arc', // Aramaic
+  'ary', // Moroccan Arabic
+  'arz', // Egyptian Arabic
+  'ckb', // Central Kurdish / Sorani
+  'dv', // Divehi
+  'fa', // Persian / Farsi
+  'he', // Hebrew
+  'iw', // Hebrew (deprecated code, still emitted by older libraries)
+  'ji', // Yiddish (deprecated code)
+  'kmr', // Northern Kurdish
+  'ks', // Kashmiri
+  'ku', // Kurdish
+  'mzn', // Mazanderani
+  'nqo', // N'Ko
+  'pnb', // Western Punjabi
+  'prs', // Dari
+  'ps', // Pashto
+  'sd', // Sindhi
+  'skr', // Saraiki
+  'syr', // Syriac
+  'ug', // Uyghur
+  'ur', // Urdu
+  'yi', // Yiddish
+]);
+
+/**
+ * Tags that host i18n libraries spell differently from the modern canonical form.
+ *
+ * The left side is a lowercased tag as it might arrive; the right side is what
+ * the plugin resolves it to. This exists because a host that says `zh-CN` and a
+ * host that says `zh-Hans` mean the same language, and bundles should not have
+ * to be registered twice.
+ */
+const LOCALE_ALIASES: Readonly<Record<string, string>> = {
+  // Chinese: region-style tags are by far the most common way hosts spell
+  // Simplified and Traditional, but the script is what actually selects the text.
+  'zh-cn': 'zh-Hans-CN',
+  'zh-sg': 'zh-Hans-SG',
+  'zh-my': 'zh-Hans-MY',
+  'zh-tw': 'zh-Hant-TW',
+  'zh-hk': 'zh-Hant-HK',
+  'zh-mo': 'zh-Hant-MO',
+  'zh-chs': 'zh-Hans',
+  'zh-cht': 'zh-Hant',
+  'zh-simplified': 'zh-Hans',
+  'zh-traditional': 'zh-Hant',
+  // Deprecated ISO-639 codes still emitted by older i18n stacks.
+  'iw': 'he',
+  'ji': 'yi',
+  'in': 'id',
+  'mo': 'ro',
+  'tl': 'fil',
+  // Persian and Dari.
+  'per': 'fa',
+  'fas': 'fa',
+  'prs': 'fa-AF',
+  // Other three-letter forms that occasionally show up.
+  'ara': 'ar',
+  'ben': 'bn',
+  'zho': 'zh',
+  'chi': 'zh',
+  'dan': 'da',
+  'deu': 'de',
+  'ger': 'de',
+  'fra': 'fr',
+  'fre': 'fr',
+  'hin': 'hi',
+  'ita': 'it',
+  'jpn': 'ja',
+  'kor': 'ko',
+  'pol': 'pl',
+  'por': 'pt',
+  'ron': 'ro',
+  'rum': 'ro',
+  'rus': 'ru',
+  'spa': 'es',
+  'swe': 'sv',
+  'tur': 'tr',
+  'ukr': 'uk',
+  'vie': 'vi',
+  'eng': 'en',
+};
+
+/** Splits on the separators host apps actually use: `-`, `_` and `.` */
+const SEPARATORS = /[-_.]+/;
+
+function titleCaseScript(value: string): string {
+  const head = value.charAt(0).toUpperCase();
+  return head + value.slice(1).toLowerCase();
+}
+
+/**
+ * Reduces any language identifier to a canonical BCP-47-ish tag.
+ *
+ * Accepts what hosts really pass: `en`, `en-US`, `en_us`, `EN-us`, `zh_CN`,
+ * `pt-BR.UTF-8`, `fa-IR`, and returns `en`, `en-US`, `en-US`, `en-US`,
+ * `zh-Hans-CN`, `pt-BR`, `fa-IR`. Returns an empty string for junk so callers
+ * can fall back rather than guess.
+ */
+export function normalizeLocale(input?: string | null): string {
+  if (typeof input !== 'string') return '';
+
+  const trimmed = input.trim();
+  if (trimmed.length === 0) return '';
+
+  // Strip POSIX charset/modifier suffixes: `ar_EG.UTF-8@calendar=islamic`.
+  const withoutModifier = trimmed.split('@')[0] ?? '';
+  const cleaned = withoutModifier.replace(/\.(utf-?8|iso[\w-]*)$/i, '');
+
+  const direct = LOCALE_ALIASES[cleaned.toLowerCase()];
+  if (direct) return direct;
+
+  const parts = cleaned.split(SEPARATORS).filter((part) => part.length > 0);
+  const rawLanguage = parts.shift();
+  if (!rawLanguage) return '';
+
+  const language = rawLanguage.toLowerCase();
+  if (!/^[a-z]{2,8}$/.test(language)) return '';
+
+  let script = '';
+  let region = '';
+
+  for (const part of parts) {
+    if (!script && /^[a-z]{4}$/i.test(part)) {
+      script = titleCaseScript(part);
+    } else if (!region && /^([a-z]{2}|\d{3})$/i.test(part)) {
+      region = part.toUpperCase();
+    }
+    // Variants, extensions and private-use subtags are dropped: they never
+    // affect which translation bundle or text direction the plugin should use.
+  }
+
+  const rebuilt = [language, script, region].filter(Boolean).join('-');
+
+  // Re-check aliases now that the shape is canonical, so `ZH_cn` also folds.
+  const aliased = LOCALE_ALIASES[rebuilt.toLowerCase()];
+  return aliased ?? rebuilt;
+}
+
+/** Breaks a language identifier into its language / script / region parts. */
+export function parseLocale(input?: string | null): ParsedLocale {
+  const tag = normalizeLocale(input);
+  if (tag.length === 0) {
+    return { language: '', script: '', region: '', tag: '' };
+  }
+
+  const parts = tag.split('-');
+  const language = (parts[0] ?? '').toLowerCase();
+  let script = '';
+  let region = '';
+
+  for (const part of parts.slice(1)) {
+    if (part.length === 4) script = titleCaseScript(part);
+    else region = part.toUpperCase();
+  }
+
+  return { language, script, region, tag };
+}
+
+/**
+ * True when text in this locale reads right-to-left.
+ *
+ * Script wins when present (`ku-Arab` is RTL even though bare `ku` may be
+ * written either way in practice); otherwise the language's default script
+ * decides. An unrecognised or empty tag is left-to-right, matching the
+ * English fallback.
+ */
+export function isRtlLocale(input?: string | null): boolean {
+  const { language, script } = parseLocale(input);
+  if (language.length === 0) return false;
+
+  // An explicit script is authoritative: `ku-Arab` is RTL, `ku-Latn` is not,
+  // and a script the plugin has never seen still resolves correctly.
+  if (script.length > 0) return RTL_SCRIPTS.has(script);
+
+  return RTL_LANGUAGES.has(language);
+}
+
+/**
+ * Ordered list of tags to try for a locale, most specific first.
+ *
+ * `zh-Hans-CN` → `['zh-Hans-CN', 'zh-Hans', 'zh-CN', 'zh', 'en']`
+ * `pt-BR`      → `['pt-BR', 'pt', 'en']`
+ * `fa`         → `['fa', 'en']`
+ *
+ * The fallback locale is appended last and deduplicated, so a bundle registered
+ * under any of these spellings is found. English stays the final fallback.
+ */
+export function localeFallbackChain(
+  input?: string | null,
+  fallbackLocale: string = DEFAULT_LOCALE
+): string[] {
+  const { language, script, region, tag } = parseLocale(input);
+  const chain: string[] = [];
+
+  const push = (candidate: string) => {
+    if (candidate.length > 0 && !chain.includes(candidate)) {
+      chain.push(candidate);
+    }
+  };
+
+  // Script outranks region: a `zh-Hans` bundle is a far better match for
+  // `zh-Hans-CN` than a `zh-CN` one, even though both drop a single subtag.
+  push(tag);
+  if (script.length > 0) push(`${language}-${script}`);
+  if (region.length > 0) push(`${language}-${region}`);
+  push(language);
+
+  const fallback = normalizeLocale(fallbackLocale);
+  if (fallback.length > 0) {
+    const parsedFallback = parseLocale(fallback);
+    push(parsedFallback.tag);
+    push(parsedFallback.language);
+  }
+
+  push(DEFAULT_LOCALE);
+
+  return chain;
+}
+
+/**
+ * Picks the best matching key out of a locale-keyed record.
+ *
+ * Lookups are case-insensitive and separator-insensitive, so a bundle
+ * registered as `zh_TW`, `zh-tw` or `zh-Hant-TW` is all found by the same
+ * request. Returns `undefined` when nothing in the chain matches.
+ */
+export function matchLocaleKey<T>(
+  locale: string | null | undefined,
+  entries: Readonly<Record<string, T>> | undefined,
+  fallbackLocale: string = DEFAULT_LOCALE
+): string | undefined {
+  if (!entries) return undefined;
+
+  // Index the record by normalized tag once, so host spelling never matters.
+  const index = new Map<string, string>();
+  for (const key of Object.keys(entries)) {
+    const normalized = normalizeLocale(key).toLowerCase();
+    if (normalized.length > 0 && !index.has(normalized)) {
+      index.set(normalized, key);
+    }
+  }
+
+  for (const candidate of localeFallbackChain(locale, fallbackLocale)) {
+    const hit = index.get(candidate.toLowerCase());
+    if (hit !== undefined) return hit;
+  }
+
+  return undefined;
+}
+
+/**
+ * Merges every bundle along the fallback chain into one map.
+ *
+ * Least specific wins first and is then overwritten by more specific entries,
+ * so a `zh` bundle can carry the shared strings while `zh-Hant` overrides only
+ * the handful that differ. Missing keys simply stay missing here — the caller
+ * layers this on top of the shipped English defaults.
+ */
+export function resolveLocaleTranslations<T extends object>(
+  locale: string | null | undefined,
+  bundles: Readonly<Record<string, T>> | undefined,
+  fallbackLocale: string = DEFAULT_LOCALE
+): Partial<T> {
+  if (!bundles) return {};
+
+  const index = new Map<string, T>();
+  for (const [key, value] of Object.entries(bundles)) {
+    const normalized = normalizeLocale(key).toLowerCase();
+    if (normalized.length > 0 && !index.has(normalized)) {
+      index.set(normalized, value);
+    }
+  }
+
+  const chain = localeFallbackChain(locale, fallbackLocale);
+  let merged: Partial<T> = {};
+
+  // Walk the chain backwards: broadest first, most specific applied last.
+  for (let i = chain.length - 1; i >= 0; i -= 1) {
+    const candidate = chain[i];
+    if (candidate === undefined) continue;
+    const bundle = index.get(candidate.toLowerCase());
+    if (bundle) merged = { ...merged, ...bundle };
+  }
+
+  return merged;
+}