@kromatv/sdk 0.1.39-canary.3579809

package/rust/kroma-i18n/src/lib.rs

@@ -0,0 +1,355 @@
+//! A small, generic i18n engine — a framework-agnostic Rust counterpart to
+//! `@kromatv/core`'s `i18n.ts`.
+//!
+//! Nothing here is application-specific: build an [`I18n`] instance from your
+//! own catalogs, default locale, and plural rules, then translate against it.
+//! Provides `{name}` interpolation, CLDR pluralization, locale
+//! normalization/detection, and a default→raw-key fallback chain.
+
+use std::collections::HashMap;
+
+mod builder;
+mod interpolate;
+mod locale;
+mod nest;
+mod plural;
+#[cfg(test)]
+mod test_support;
+
+pub use builder::{BuildError, Builder};
+pub use interpolate::interpolate;
+pub(crate) use nest::expand_refs;
+pub use nest::has_unresolved_ref;
+pub use plural::{cldr, one_other, zero_one_other, Category, PluralRule};
+
+fn numeric(vars: &[(&str, &str)], name: &str) -> Option<i64> {
+    vars.iter()
+        .find(|(k, _)| *k == name)
+        .and_then(|(_, v)| v.parse::<i64>().ok())
+}
+
+/// A configured translation engine. Cheap to share behind an `Arc`/`OnceLock`;
+/// build once at startup.
+pub struct I18n {
+    default: String,
+    locales: Vec<Locale>,
+    plural: PluralRule,
+}
+
+struct Locale {
+    code: String,
+    label_key: String,
+    entries: HashMap<String, String>,
+}
+
+/// A locale's code and the message key holding its native display name.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct LocaleInfo<'a> {
+    pub code: &'a str,
+    pub label_key: &'a str,
+}
+
+impl I18n {
+    /// Start building an engine.
+    pub fn builder() -> Builder {
+        Builder::default()
+    }
+
+    /// The configured fallback locale.
+    pub fn default_locale(&self) -> &str {
+        &self.default
+    }
+
+    /// Supported locale codes, default first.
+    pub fn supported(&self) -> impl Iterator<Item = &str> {
+        self.locales.iter().map(|l| l.code.as_str())
+    }
+
+    /// Every locale's code + native-label key, default first.
+    pub fn locales(&self) -> impl Iterator<Item = LocaleInfo<'_>> {
+        self.locales.iter().map(|l| LocaleInfo {
+            code: &l.code,
+            label_key: &l.label_key,
+        })
+    }
+
+    /// Whether `code` is a supported locale.
+    pub fn is_locale(&self, code: &str) -> bool {
+        self.locales.iter().any(|l| l.code == code)
+    }
+
+    /// Whether `key` exists in the default (authoritative) catalog.
+    pub fn is_message_key(&self, key: &str) -> bool {
+        self.lookup(&self.default, key).is_some()
+    }
+
+    fn lookup(&self, code: &str, key: &str) -> Option<&str> {
+        self.locales
+            .iter()
+            .find(|l| l.code == code)?
+            .entries
+            .get(key)
+            .map(String::as_str)
+    }
+
+    // The category is chosen from `tag` (see `translate`); the variant is then
+    // looked up under the resolved `code`.
+    fn variant_in(&self, code: &str, tag: &str, stem: &str, count: i64) -> Option<String> {
+        // An explicit `_zero` wins at zero even where the rule has no zero
+        // category, because "nothing yet" is usually its own sentence.
+        if count == 0 {
+            let zero = format!("{stem}_zero");
+            if self.lookup(code, &zero).is_some() {
+                return Some(zero);
+            }
+        }
+        let category = format!("{stem}_{}", (self.plural)(tag, count).suffix());
+        if self.lookup(code, &category).is_some() {
+            return Some(category);
+        }
+        let other = format!("{stem}_other");
+        if self.lookup(code, &other).is_some() {
+            return Some(other);
+        }
+        None
+    }
+
+    fn resolve_in(
+        &self,
+        code: &str,
+        tag: &str,
+        key: &str,
+        vars: &[(&str, &str)],
+    ) -> Option<String> {
+        if let Some(count) = numeric(vars, "count") {
+            if let Some(hit) = self.variant_in(code, tag, key, count) {
+                return Some(hit);
+            }
+        }
+        for (name, _) in vars {
+            if *name == "count" {
+                continue;
+            }
+            let Some(count) = numeric(vars, name) else {
+                continue;
+            };
+            if let Some(hit) = self.variant_in(code, tag, &format!("{key}_{name}"), count) {
+                return Some(hit);
+            }
+        }
+        None
+    }
+
+    // A variant is only ever taken from the catalog that will also supply the
+    // template, so a locale cannot borrow another language's singular purely
+    // because that language happens to declare one.
+    fn resolve_plural_key(
+        &self,
+        tag: &str,
+        code: &str,
+        key: &str,
+        vars: &[(&str, &str)],
+    ) -> String {
+        if let Some(hit) = self.resolve_in(code, tag, key, vars) {
+            return hit;
+        }
+        if self.lookup(code, key).is_some() {
+            return key.to_string();
+        }
+        self.resolve_in(&self.default, tag, key, vars)
+            .unwrap_or_else(|| key.to_string())
+    }
+
+    /// Translate `key` in `locale`, falling back to the default locale then the
+    /// raw key. Regional tags resolve to their base catalog (`fr_CH` → `fr`). A
+    /// numeric `count` var selects a plural variant and, like every var, is
+    /// interpolated into `{count}`.
+    pub fn translate(&self, locale: &str, key: &str, vars: &[(&str, &str)]) -> String {
+        let resolved = self.resolve_code(locale);
+        let code = resolved.unwrap_or(&self.default);
+        // A plural rule can only read a language tag, so it sees the caller's
+        // own when that is what it is (a rule telling `pt_BR` from `pt_PT`
+        // needs the region), and the resolved code when the caller passed
+        // something else a rule cannot parse, such as the endonym "Français".
+        let tag = resolved.unwrap_or(code);
+        let lookup_key = if vars.is_empty() {
+            key.to_string()
+        } else {
+            self.resolve_plural_key(tag, code, key, vars)
+        };
+        let template = self
+            .lookup(code, &lookup_key)
+            .or_else(|| self.lookup(&self.default, &lookup_key))
+            .unwrap_or(key);
+        interpolate(template, vars)
+    }
+
+    /// Short alias for [`translate`](Self::translate).
+    pub fn t(&self, locale: &str, key: &str, vars: &[(&str, &str)]) -> String {
+        self.translate(locale, key, vars)
+    }
+
+    /// A translation function bound to one locale (unknown codes fall back to the
+    /// default, so this never fails).
+    pub fn translator<'a>(&'a self, locale: &str) -> Translator<'a> {
+        let code = self.resolve_code(locale).unwrap_or(&self.default);
+        Translator {
+            i18n: self,
+            locale: code,
+        }
+    }
+}
+
+/// A translation function bound to one locale of an [`I18n`].
+#[derive(Clone, Copy)]
+pub struct Translator<'a> {
+    i18n: &'a I18n,
+    locale: &'a str,
+}
+
+impl<'a> Translator<'a> {
+    /// The bound locale.
+    pub fn locale(&self) -> &'a str {
+        self.locale
+    }
+
+    /// Translate `key` (see [`I18n::translate`]).
+    pub fn t(&self, key: &str, vars: &[(&str, &str)]) -> String {
+        self.i18n.translate(self.locale, key, vars)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_support::fixture;
+
+    #[test]
+    fn default_leads_and_supported() {
+        let i = fixture();
+        assert_eq!(i.default_locale(), "fr");
+        assert_eq!(i.supported().collect::<Vec<_>>(), vec!["fr", "en"]);
+        assert!(i.is_locale("en") && !i.is_locale("de"));
+        assert!(i.is_message_key("hi") && !i.is_message_key("nope"));
+    }
+
+    fn asymmetric() -> I18n {
+        I18n::builder()
+            .default_locale("fr")
+            .catalog_json(
+                "fr",
+                r#"{ "n": "{count} objets", "n_one": "{count} objet", "n_zero": "Aucun objet",
+                     "moved": "{files} fichiers", "moved_files_one": "{files} fichier" }"#,
+            )
+            .catalog_json("en", r#"{ "n": "{count} items" }"#)
+            .build()
+            .unwrap()
+    }
+
+    #[test]
+    fn a_locale_never_borrows_another_language_singular_it_did_not_declare() {
+        let i = asymmetric();
+
+        assert_eq!(i.t("en", "n", &[("count", "1")]), "1 items");
+        assert_eq!(i.t("fr", "n", &[("count", "1")]), "1 objet");
+    }
+
+    #[test]
+    fn a_locale_that_does_not_know_the_key_still_pluralizes_in_the_default() {
+        let i = asymmetric();
+
+        assert_eq!(i.t("de", "n", &[("count", "1")]), "1 objet");
+    }
+
+    #[test]
+    fn an_explicit_zero_variant_wins_at_zero() {
+        let i = asymmetric();
+
+        assert_eq!(i.t("fr", "n", &[("count", "0")]), "Aucun objet");
+        assert_eq!(i.t("en", "n", &[("count", "0")]), "0 items");
+    }
+
+    #[test]
+    fn a_quantity_that_is_not_called_count_still_selects_a_variant() {
+        let i = asymmetric();
+
+        assert_eq!(i.t("fr", "moved", &[("files", "1")]), "1 fichier");
+        assert_eq!(i.t("fr", "moved", &[("files", "4")]), "4 fichiers");
+    }
+
+    #[test]
+    fn a_message_with_no_numeric_var_is_untouched_by_pluralization() {
+        let i = fixture();
+
+        assert_eq!(i.t("fr", "hi", &[("name", "Ana")]), "Salut Ana");
+    }
+
+    #[test]
+    fn pluralization_default_one_other() {
+        let i = fixture();
+        assert_eq!(i.t("en", "seasons", &[("count", "1")]), "1 season");
+        assert_eq!(i.t("en", "seasons", &[("count", "0")]), "0 seasons");
+        assert_eq!(i.t("fr", "seasons", &[("count", "1")]), "1 saison");
+        assert_eq!(i.t("fr", "seasons", &[("count", "2")]), "2 saisons");
+        // A key with no `_one` variant just uses the base key (no rule needed).
+        assert_eq!(i.t("en", "hi", &[("name", "A"), ("count", "1")]), "Hi A");
+    }
+
+    #[test]
+    fn a_missing_plural_variant_falls_back_to_other_before_the_bare_key() {
+        let i = I18n::builder()
+            .default_locale("en")
+            .catalog_json("en", r#"{ "seasons_other": "{count} seasons" }"#)
+            .build()
+            .unwrap();
+        assert_eq!(i.t("en", "seasons", &[("count", "1")]), "1 seasons");
+    }
+
+    #[test]
+    fn plural_rule_is_pluggable() {
+        // No baked-in language table: making French treat 0 as singular takes a
+        // custom rule, proving the engine doesn't hardcode CLDR.
+        fn fr_zero_is_one(locale: &str, count: i64) -> Category {
+            if locale.starts_with("fr") && count == 0 {
+                Category::One
+            } else {
+                one_other(locale, count)
+            }
+        }
+        let i = I18n::builder()
+            .default_locale("fr")
+            .plural_rule(fr_zero_is_one)
+            .catalog_json(
+                "fr",
+                r#"{ "seasons": "{count} saisons", "seasons_one": "{count} saison" }"#,
+            )
+            .build()
+            .unwrap();
+        assert_eq!(i.t("fr", "seasons", &[("count", "0")]), "0 saison");
+        assert_eq!(i.t("fr", "seasons", &[("count", "2")]), "2 saisons");
+    }
+
+    #[test]
+    fn fallback_and_translator() {
+        let i = fixture();
+        assert_eq!(i.t("en", "lang.fr", &[]), "Français");
+        assert_eq!(i.t("en", "missing.key", &[]), "missing.key");
+        let tr = i.translator("en-US");
+        assert_eq!(tr.locale(), "en");
+        assert_eq!(tr.t("hi", &[("name", "Sam")]), "Hi Sam");
+        assert_eq!(i.translator("xx").locale(), "fr");
+    }
+
+    #[test]
+    fn the_supported_list_puts_the_default_first() {
+        // The picker renders in this order, and the default is what an
+        // unconfigured client gets - showing it first is the point.
+        let i18n = fixture();
+        let codes: Vec<&str> = i18n.supported().collect();
+        assert_eq!(codes.first(), Some(&"fr"));
+        assert!(codes.contains(&"en"));
+
+        let labelled: Vec<&str> = i18n.locales().map(|l| l.code).collect();
+        assert_eq!(codes, labelled, "both views agree on the order");
+    }
+}

package/rust/kroma-i18n/src/locale.rs

@@ -0,0 +1,133 @@
+//! Locale-tag algebra: which supported catalog a BCP-47 tag resolves to.
+
+use crate::I18n;
+
+impl I18n {
+    // An exact match wins first (so a regional catalog like `fr-CH` wins if
+    // shipped), else the base language with region and case normalized.
+    pub(crate) fn resolve_code(&self, tag: &str) -> Option<&str> {
+        let trimmed = tag.trim();
+        if trimmed.is_empty() {
+            return None;
+        }
+        if let Some(l) = self.locales.iter().find(|l| l.code == trimmed) {
+            return Some(&l.code);
+        }
+        let base = base_language(trimmed);
+        self.locales
+            .iter()
+            .find(|l| base_language(&l.code) == base)
+            .map(|l| l.code.as_str())
+    }
+
+    /// Map a BCP-47 tag (`"en-US"`, `"FR"`, `"fr_CH"`) or a native display name
+    /// (from the `label_key` catalog entry) to a supported locale, or `None`.
+    pub fn normalize_locale(&self, tag: &str) -> Option<&str> {
+        if let Some(code) = self.resolve_code(tag) {
+            return Some(code);
+        }
+        // Native display name (data-driven from each locale's own label entry).
+        let trimmed = tag.trim();
+        self.locales
+            .iter()
+            .find(|l| l.entries.get(&l.label_key).map(String::as_str) == Some(trimmed))
+            .map(|l| l.code.as_str())
+    }
+
+    /// Best locale: an explicit `preferred` wins, then the first resolvable
+    /// `Accept-Language` entry, else the default.
+    pub fn detect_locale(&self, preferred: Option<&str>, accept_language: Option<&str>) -> &str {
+        if let Some(loc) = preferred.and_then(|p| self.normalize_locale(p)) {
+            return loc;
+        }
+        if let Some(header) = accept_language {
+            for part in header.split(',') {
+                let tag = part.split(';').next().unwrap_or("").trim();
+                if let Some(loc) = self.normalize_locale(tag) {
+                    return loc;
+                }
+            }
+        }
+        &self.default
+    }
+}
+
+// The base language subtag, region stripped and lowercased: `"fr_CH"` → `"fr"`,
+// `"en-US"` → `"en"`, `"FR"` → `"fr"`.
+fn base_language(tag: &str) -> String {
+    tag.split(['-', '_'])
+        .next()
+        .unwrap_or("")
+        .to_ascii_lowercase()
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::test_support::fixture;
+    use crate::I18n;
+
+    #[test]
+    fn normalize_and_detect() {
+        let i = fixture();
+        assert_eq!(i.normalize_locale("en-US"), Some("en"));
+        assert_eq!(i.normalize_locale("FR"), Some("fr"));
+        assert_eq!(i.normalize_locale("Français"), Some("fr"));
+        assert_eq!(i.normalize_locale("English"), Some("en"));
+        assert_eq!(i.normalize_locale("de"), None);
+        assert_eq!(i.detect_locale(Some("de"), Some("en-US,en;q=0.9")), "en");
+        assert_eq!(i.detect_locale(None, None), "fr");
+    }
+
+    #[test]
+    fn regional_variants_resolve_to_base() {
+        let i = fixture();
+        for tag in ["fr", "fr_FR", "fr-CH", "FR", "fr_CA"] {
+            assert_eq!(i.normalize_locale(tag), Some("fr"), "tag {tag}");
+            assert_eq!(
+                i.t(tag, "seasons", &[("count", "2")]),
+                "2 saisons",
+                "tag {tag}"
+            );
+        }
+        assert_eq!(i.t("en-GB", "hi", &[("name", "Jo")]), "Hi Jo");
+        let r = I18n::builder()
+            .default_locale("en")
+            .catalog_json("en", r#"{ "color": "color" }"#)
+            .catalog_json("en-GB", r#"{ "color": "colour" }"#)
+            .build()
+            .unwrap();
+        assert_eq!(r.t("en-GB", "color", &[]), "colour"); // exact
+        assert_eq!(r.t("en-AU", "color", &[]), "color"); // base fallback
+    }
+
+    #[test]
+    fn a_browser_header_picks_the_first_locale_we_actually_have() {
+        // Accept-Language is a ranked list of things the browser wants, most of
+        // which we will not have. Taking the first ENTRY rather than the first
+        // SUPPORTED one would drop everyone whose top choice we lack to the
+        // default.
+        let i18n = fixture();
+        assert_eq!(
+            i18n.detect_locale(None, Some("de-DE,de;q=0.9,en;q=0.8")),
+            "en"
+        );
+        // Quality values are stripped before matching.
+        assert_eq!(i18n.detect_locale(None, Some("en;q=0.8")), "en");
+        // Region and case are normalized away.
+        assert_eq!(i18n.detect_locale(None, Some("EN-GB")), "en");
+        // Nothing we have -> the default.
+        assert_eq!(i18n.detect_locale(None, Some("de,it,ja")), "fr");
+        assert_eq!(i18n.detect_locale(None, None), "fr");
+    }
+
+    #[test]
+    fn an_account_preference_outranks_the_browser() {
+        // The user chose this in their profile; the browser's header is a guess.
+        let i18n = fixture();
+        assert_eq!(i18n.detect_locale(Some("en"), Some("fr")), "en");
+        // ...but a preference we cannot serve falls through to the header
+        // rather than to the default.
+        assert_eq!(i18n.detect_locale(Some("de"), Some("en")), "en");
+        assert_eq!(i18n.detect_locale(Some(""), Some("en")), "en");
+    }
+}

package/rust/kroma-i18n/src/nest.rs

@@ -0,0 +1,185 @@
+//! Build-time expansion of `$t(other.key)` references inside catalog values,
+//! so a term written in one place reads the same everywhere it is quoted.
+//!
+//! Runs once, in [`crate::Builder::build`], which is what lets
+//! [`crate::interpolate`] stay a single pass: a variable carrying user text can
+//! never reach back into the catalog.
+
+use std::collections::{HashMap, HashSet};
+
+/// Where a `$t(...)` reference sits in a template, and which key it names.
+struct Ref {
+    start: usize,
+    end: usize,
+    key: String,
+}
+
+fn next_ref(template: &str, mut from: usize) -> Option<Ref> {
+    loop {
+        let start = template[from..].find("$t(")? + from;
+        let open = start + 3;
+        let close = template[open..].find(')')? + open;
+        let key = template[open..close].trim();
+        if key.is_empty()
+            || !key
+                .bytes()
+                .all(|b| b.is_ascii_alphanumeric() || b"._-".contains(&b))
+        {
+            from = open;
+            continue;
+        }
+        return Some(Ref {
+            start,
+            end: close + 1,
+            key: key.to_string(),
+        });
+    }
+}
+
+/// Whether `template` still names a key, i.e. [`expand_refs`] could not resolve
+/// it. A catalog that ships one of these has a typo or a cycle.
+pub fn has_unresolved_ref(template: &str) -> bool {
+    next_ref(template, 0).is_some()
+}
+
+fn resolve(
+    key: &str,
+    own: &HashMap<String, String>,
+    fallback: &HashMap<String, String>,
+    done: &mut HashMap<String, String>,
+    visiting: &mut HashSet<String>,
+) -> Option<String> {
+    if let Some(cached) = done.get(key) {
+        return Some(cached.clone());
+    }
+    if visiting.contains(key) {
+        return None;
+    }
+    let template = own.get(key).or_else(|| fallback.get(key))?.clone();
+
+    visiting.insert(key.to_string());
+    let mut out = String::with_capacity(template.len());
+    let mut at = 0;
+    while let Some(r) = next_ref(&template, at) {
+        out.push_str(&template[at..r.start]);
+        match resolve(&r.key, own, fallback, done, visiting) {
+            Some(value) => out.push_str(&value),
+            None => out.push_str(&template[r.start..r.end]),
+        }
+        at = r.end;
+    }
+    out.push_str(&template[at..]);
+    visiting.remove(key);
+
+    done.insert(key.to_string(), out.clone());
+    Some(out)
+}
+
+/// Expand every `$t(...)` reference in `own`, resolving against `own` first and
+/// then `fallback`. A reference naming a missing key, or closing a cycle, is
+/// left standing rather than failing the build: a catalog is data, and a bad
+/// entry must not stop the server from booting. Guard the shipped catalogs with
+/// [`has_unresolved_ref`] in a test instead.
+pub fn expand_refs(
+    own: HashMap<String, String>,
+    fallback: &HashMap<String, String>,
+) -> HashMap<String, String> {
+    // Most catalogs quote nothing. Reproducing a few thousand entries exactly,
+    // allocating twice per key to do it, is the whole cost of the feature for
+    // everyone not using it, and this runs at boot.
+    if !own.values().any(|t| t.contains("$t(")) {
+        return own;
+    }
+    let mut done = HashMap::with_capacity(own.len());
+    let mut visiting = HashSet::new();
+    let mut out = HashMap::with_capacity(own.len());
+    for (key, template) in &own {
+        if !template.contains("$t(") {
+            out.insert(key.clone(), template.clone());
+            continue;
+        }
+        let value = resolve(key, &own, fallback, &mut done, &mut visiting)
+            .unwrap_or_else(|| template.clone());
+        out.insert(key.clone(), value);
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn cat(pairs: &[(&str, &str)]) -> HashMap<String, String> {
+        pairs
+            .iter()
+            .map(|(k, v)| ((*k).to_string(), (*v).to_string()))
+            .collect()
+    }
+
+    #[test]
+    fn a_reference_is_replaced_by_the_value_it_names() {
+        let own = cat(&[("brand", "KROMA"), ("hi", "Welcome to $t(brand)")]);
+
+        let out = expand_refs(own, &HashMap::new());
+
+        assert_eq!(out["hi"], "Welcome to KROMA");
+    }
+
+    #[test]
+    fn a_reference_resolves_in_its_own_locale_before_the_default() {
+        let own = cat(&[("unit", "saison"), ("of", "Une $t(unit)")]);
+        let fallback = cat(&[("unit", "season")]);
+
+        let out = expand_refs(own, &fallback);
+
+        assert_eq!(out["of"], "Une saison");
+    }
+
+    #[test]
+    fn a_reference_the_locale_does_not_define_falls_back_to_the_default() {
+        let own = cat(&[("hi", "Bonjour $t(brand)")]);
+        let fallback = cat(&[("brand", "KROMA")]);
+
+        let out = expand_refs(own, &fallback);
+
+        assert_eq!(out["hi"], "Bonjour KROMA");
+    }
+
+    #[test]
+    fn a_chain_of_references_expands_all_the_way_down() {
+        let own = cat(&[("a", "A"), ("b", "$t(a)B"), ("c", "$t(b)C")]);
+
+        let out = expand_refs(own, &HashMap::new());
+
+        assert_eq!(out["c"], "ABC");
+    }
+
+    #[test]
+    fn a_reference_to_a_missing_key_is_left_standing() {
+        let own = cat(&[("hi", "Hello $t(nope)")]);
+
+        let out = expand_refs(own, &HashMap::new());
+
+        assert_eq!(out["hi"], "Hello $t(nope)");
+        assert!(has_unresolved_ref(&out["hi"]));
+    }
+
+    #[test]
+    fn a_cycle_is_broken_rather_than_recursed_forever() {
+        let own = cat(&[("a", "x$t(b)"), ("b", "y$t(a)")]);
+
+        let out = expand_refs(own, &HashMap::new());
+
+        assert!(has_unresolved_ref(&out["a"]));
+    }
+
+    #[test]
+    fn a_value_with_no_reference_is_untouched() {
+        let own = cat(&[("hi", "Hello {name}"), ("odd", "cost: $t( ) and $tx")]);
+
+        let out = expand_refs(own, &HashMap::new());
+
+        assert_eq!(out["hi"], "Hello {name}");
+        assert_eq!(out["odd"], "cost: $t( ) and $tx");
+    }
+}