youtube-legend-cli 0.4.0

//! Interface localisation.
//!
//! The catalogue is compiled in, not loaded at run time: every string
//! is a `&'static str` selected by an exhaustive `match` over
//! [`Message`]. A missing translation is a compile error, never a
//! run-time fallback to English.
//!
//! # Two entry points
//!
//! - [`crate::i18n::t`] reads the process-wide interface locale. Use it in
//!   production code.
//! - [`Message::text`] takes the locale explicitly and touches no
//!   global state. Use it in tests, so an assertion never depends on
//!   the locale of the machine running the suite.
//!
//! # Resolution order
//!
//! 1. the `--ui-lang` flag
//! 2. the `ui_lang` key of the TOML config file
//! 3. the operating-system locale, read through [`sys_locale`]
//! 4. English
//!
//! Steps 1 and 2 are merged by [`crate::cli::Cli::apply_config_overrides`]
//! and handed to [`crate::i18n::init`]. Steps 3 and 4 happen inside
//! [`crate::i18n::current`] when [`crate::i18n::init`] was never
//! called. There is deliberately no environment
//! variable in this chain: the project forbids product env knobs, and
//! `sys_locale` already reads the OS API on every platform.
//!
//! # Which strings are localised
//!
//! Human-facing prose on `stderr`. The `--json` envelope, tracing
//! fields, and machine-readable identifiers stay in English so
//! downstream parsers keep working regardless of the operator locale.

mod en;
mod message;
mod pt_br;

#[cfg(feature = "i18n-rtl")]
mod ar;
#[cfg(feature = "i18n-europe")]
mod de;
#[cfg(feature = "i18n-europe")]
mod es;
#[cfg(feature = "i18n-europe")]
mod fr;
#[cfg(feature = "i18n-rtl")]
mod he;
#[cfg(feature = "i18n-europe")]
mod it;
#[cfg(feature = "i18n-cjk")]
mod ja;
#[cfg(feature = "i18n-cjk")]
mod ko;
#[cfg(feature = "i18n-cjk")]
mod zh_hans;
#[cfg(feature = "i18n-cjk")]
mod zh_hant;

pub use message::Message;

use fluent_langneg::negotiate::{negotiate_languages, NegotiationStrategy};
use std::str::FromStr;
use std::sync::OnceLock;

/// An interface locale this build can render.
///
/// Only English and Brazilian Portuguese are always present. Every
/// other variant exists solely when its Cargo feature is enabled, which
/// is what keeps the `match` in [`Message::text`] exhaustive without a
/// catch-all arm.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Language {
    /// English (`en`).
    En,
    /// Brazilian Portuguese (`pt-BR`).
    PtBr,
    /// Spanish (`es`).
    #[cfg(feature = "i18n-europe")]
    Es,
    /// French (`fr`).
    #[cfg(feature = "i18n-europe")]
    Fr,
    /// German (`de`).
    #[cfg(feature = "i18n-europe")]
    De,
    /// Italian (`it`).
    #[cfg(feature = "i18n-europe")]
    It,
    /// Simplified Chinese (`zh-Hans`).
    #[cfg(feature = "i18n-cjk")]
    ZhHans,
    /// Traditional Chinese (`zh-Hant`).
    #[cfg(feature = "i18n-cjk")]
    ZhHant,
    /// Japanese (`ja`).
    #[cfg(feature = "i18n-cjk")]
    Ja,
    /// Korean (`ko`).
    #[cfg(feature = "i18n-cjk")]
    Ko,
    /// Arabic (`ar`).
    #[cfg(feature = "i18n-rtl")]
    Ar,
    /// Hebrew (`he`).
    #[cfg(feature = "i18n-rtl")]
    He,
}

impl Language {
    /// Canonical BCP 47 tag for this locale.
    #[must_use]
    pub fn as_tag(self) -> &'static str {
        match self {
            Language::En => "en",
            Language::PtBr => "pt-BR",
            #[cfg(feature = "i18n-europe")]
            Language::Es => "es",
            #[cfg(feature = "i18n-europe")]
            Language::Fr => "fr",
            #[cfg(feature = "i18n-europe")]
            Language::De => "de",
            #[cfg(feature = "i18n-europe")]
            Language::It => "it",
            #[cfg(feature = "i18n-cjk")]
            Language::ZhHans => "zh-Hans",
            #[cfg(feature = "i18n-cjk")]
            Language::ZhHant => "zh-Hant",
            #[cfg(feature = "i18n-cjk")]
            Language::Ja => "ja",
            #[cfg(feature = "i18n-cjk")]
            Language::Ko => "ko",
            #[cfg(feature = "i18n-rtl")]
            Language::Ar => "ar",
            #[cfg(feature = "i18n-rtl")]
            Language::He => "he",
        }
    }

    /// Every locale compiled into this binary, in declaration order.
    #[must_use]
    pub fn compiled() -> &'static [Language] {
        &[
            Language::En,
            Language::PtBr,
            #[cfg(feature = "i18n-europe")]
            Language::Es,
            #[cfg(feature = "i18n-europe")]
            Language::Fr,
            #[cfg(feature = "i18n-europe")]
            Language::De,
            #[cfg(feature = "i18n-europe")]
            Language::It,
            #[cfg(feature = "i18n-cjk")]
            Language::ZhHans,
            #[cfg(feature = "i18n-cjk")]
            Language::ZhHant,
            #[cfg(feature = "i18n-cjk")]
            Language::Ja,
            #[cfg(feature = "i18n-cjk")]
            Language::Ko,
            #[cfg(feature = "i18n-rtl")]
            Language::Ar,
            #[cfg(feature = "i18n-rtl")]
            Language::He,
        ]
    }

    /// Comma-separated list of every compiled tag, for help text and
    /// error messages.
    #[must_use]
    pub fn compiled_tags() -> String {
        Language::compiled()
            .iter()
            .map(|l| l.as_tag())
            .collect::<Vec<_>>()
            .join(", ")
    }

    /// Resolve a locale string against the compiled catalogue.
    ///
    /// Accepts anything an operating system or an operator is likely to
    /// produce: `pt_BR.UTF-8`, `PT-br`, `zh-CN`, `zh`. Matching is
    /// language negotiation, not string equality, so `zh-CN` reaches
    /// `zh-Hans` through CLDR likely-subtag expansion and `pt` reaches
    /// `pt-BR` because it is the only Portuguese catalogue compiled in.
    ///
    /// Returns `None` when no compiled locale matches, which is the
    /// signal to reject an explicit `--ui-lang` rather than silently
    /// fall back.
    #[must_use]
    pub fn from_tag(raw: &str) -> Option<Language> {
        let requested = negotiable(raw)?;
        let available: Vec<NegotiableId> = Language::compiled()
            .iter()
            .filter_map(|l| negotiable(l.as_tag()))
            .collect();
        let matched =
            negotiate_languages(&[requested], &available, None, NegotiationStrategy::Lookup);
        let winner = matched.first()?.to_string();
        Language::compiled()
            .iter()
            .copied()
            .find(|l| negotiable(l.as_tag()).map(|id| id.to_string()).as_deref() == Some(&winner))
    }
}

/// The identifier type [`fluent_langneg`] negotiates on.
///
/// `fluent-langneg` 0.14 is built on `icu_locid`, while the CLI keeps
/// its own tags in `unic-langid`. The two crates model the same BCP 47
/// data but are unrelated types, so the boundary between them is a
/// canonical tag string — the one representation both agree on.
pub(crate) type NegotiableId = fluent_langneg::LanguageIdentifier;

/// Parse a locale string into a [`NegotiableId`], applying the same
/// normalisation the rest of the crate uses.
pub(crate) fn negotiable(tag: &str) -> Option<NegotiableId> {
    NegotiableId::from_str(&normalise_locale_string(tag)).ok()
}

/// Process-wide interface locale. Written at most once, by [`init`].
static UI_LANGUAGE: OnceLock<Language> = OnceLock::new();

/// Pin the interface locale for the rest of the process.
///
/// Call this once, as early as possible, with the locale resolved from
/// `--ui-lang` and the config file. A second call is a no-op: the value
/// is immutable by construction, which is why it lives in a
/// [`OnceLock`] rather than behind a lock.
///
/// Passing `None` leaves the slot untouched so [`current`] can resolve
/// the system locale lazily.
pub fn init(language: Option<Language>) {
    #[cfg(windows)]
    console::enable_utf8();
    if let Some(lang) = language {
        // `set` fails only when the slot is already populated, which
        // means an earlier call already pinned the locale. Nothing to
        // repair, so the result is intentionally discarded.
        let _ = UI_LANGUAGE.set(lang);
    }
}

/// The interface locale in effect.
///
/// Resolves the operating-system locale on first use when [`init`] was
/// never given an explicit choice, and falls back to English when the
/// system locale names something this build does not carry.
#[must_use]
pub fn current() -> Language {
    *UI_LANGUAGE.get_or_init(detect_system_language)
}

/// Render `msg` in the interface locale returned by [`current`].
#[must_use]
pub fn t(msg: Message) -> &'static str {
    msg.text(current())
}

/// Read the operating-system locale and map it onto a compiled
/// catalogue, defaulting to English.
///
/// [`sys_locale::get_locale`] queries the platform API — `GetUserDefaultLocaleName`
/// on Windows, `CFLocale` on Apple platforms, the POSIX locale on the
/// rest — which is why the project forbids reading `LANG` by hand.
#[must_use]
pub fn detect_system_language() -> Language {
    sys_locale::get_locale()
        .as_deref()
        .and_then(Language::from_tag)
        .unwrap_or(Language::En)
}

/// Primary subtag of a locale string: `pt-BR`, `pt_BR.UTF-8` and `PT`
/// all reduce to `pt`.
///
/// This is the single implementation in the crate. It exists for the
/// places that genuinely need the bare language — the
/// `navigator.languages` chain advertised by the headless provider —
/// and nowhere else. Code that needs to keep the region or the script
/// must use [`crate::cli::LanguageArg`] instead.
#[must_use]
pub fn primary_subtag(locale: &str) -> String {
    locale
        .split(['-', '_', '.'])
        .next()
        .unwrap_or(locale)
        .to_lowercase()
}

/// Normalise the shapes an OS or an operator may hand us into something
/// [`NegotiableId`] accepts: trim, drop the `.UTF-8` style
/// encoding suffix, drop the `@euro` style modifier, and unify `_` with
/// `-`.
pub(crate) fn normalise_locale_string(raw: &str) -> String {
    let trimmed = raw.trim();
    let without_modifier = trimmed.split('@').next().unwrap_or(trimmed);
    let without_encoding = without_modifier
        .split('.')
        .next()
        .unwrap_or(without_modifier);
    without_encoding.replace('_', "-")
}

#[cfg(windows)]
mod console {
    /// Code page identifier for UTF-8, as accepted by the Win32
    /// console API.
    ///
    /// Compiled default behind `i18n.windows_console_code_page`.
    const DEFAULT_CP_UTF8: u32 = 65001;

    /// Console code page forced on Windows.
    ///
    /// Resolves `i18n.windows_console_code_page`, falling back to
    /// [`DEFAULT_CP_UTF8`]. Only identifiers Windows can accept are
    /// allowed through; anything else would make both calls fail and
    /// leave the console on its inherited code page.
    fn console_code_page() -> u32 {
        crate::config::tuning_u32_in_range(
            "i18n.windows_console_code_page",
            DEFAULT_CP_UTF8,
            1,
            65_535,
        )
    }

    #[link(name = "kernel32")]
    extern "system" {
        fn SetConsoleOutputCP(code_page: u32) -> i32;
        fn SetConsoleCP(code_page: u32) -> i32;
    }

    /// Switch both console code pages to UTF-8 so accented output
    /// reaches the terminal intact.
    ///
    /// Both calls are best-effort: they fail when the process has no
    /// console attached (a service, or output redirected to a file),
    /// and in that case there is no code page to fix in the first
    /// place.
    pub(super) fn enable_utf8() {
        // SAFETY: both functions take a plain `u32` code page by value
        // and return a BOOL. They read no pointer supplied by us and
        // write to no memory we own, so there is no aliasing or
        // lifetime obligation to uphold. `kernel32` is linked by
        // default on every supported Windows target.
        let code_page = console_code_page();
        unsafe {
            SetConsoleOutputCP(code_page);
            SetConsoleCP(code_page);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Every compiled catalogue must name every output format the
    /// parser accepts, in the message it shows when one is rejected.
    ///
    /// The expected set is DERIVED from `FormatArg`, so a fourth format
    /// fails this until all twelve catalogues have been taught about
    /// it. Written after `vtt` shipped and all twelve went on saying
    /// "txt or srt": an error message that lists the legal values while
    /// omitting one tells the operator a legal value is illegal.
    ///
    /// Under the default feature set only English and Brazilian
    /// Portuguese compile, so the other ten are reached by
    /// `--features i18n-full` — which is why that build is part of the
    /// gate set rather than an optional extra.
    #[test]
    fn every_catalogue_names_every_accepted_output_format() {
        use clap::ValueEnum;

        let spellings: Vec<String> = crate::cli::FormatArg::value_variants()
            .iter()
            .map(|variant| {
                variant
                    .to_possible_value()
                    .expect("no FormatArg variant is skipped")
                    .get_name()
                    .to_string()
            })
            .collect();
        assert!(
            spellings.len() >= 2,
            "only {} spelling(s) were derived, so this test proved nothing",
            spellings.len()
        );

        let mut checked = 0_usize;
        for language in Language::compiled() {
            let rendered = Message::ConfigInvalidFormat.text(*language);
            for spelling in &spellings {
                assert!(
                    rendered.contains(spelling.as_str()),
                    "the {} catalogue renders the invalid-format message as \
                     {rendered:?}, which never mentions the accepted spelling \
                     {spelling:?}",
                    language.as_tag()
                );
            }
            checked += 1;
        }

        assert!(
            checked >= 2,
            "only {checked} catalogue(s) were compared, so this test proved nothing"
        );
    }

    /// Every message must carry a non-empty translation in both
    /// always-compiled catalogues. The `match` arms are exhaustive by
    /// construction, so this test guards against the remaining failure
    /// mode: an arm that compiles but returns an empty string.
    #[test]
    fn every_message_has_english_and_brazilian_portuguese() {
        for msg in Message::all() {
            let english = msg.text(Language::En);
            let portuguese = msg.text(Language::PtBr);
            assert!(!english.is_empty(), "empty English text for {msg:?}");
            assert!(
                !portuguese.is_empty(),
                "empty Brazilian Portuguese text for {msg:?}"
            );
        }
    }

    /// The two baseline catalogues must actually differ. A copy-paste
    /// that left an English string in the Portuguese file would pass
    /// the emptiness check above but ship an untranslated binary.
    #[test]
    fn portuguese_translates_the_bulk_of_the_catalogue() {
        let identical = Message::all()
            .iter()
            .filter(|m| m.text(Language::En) == m.text(Language::PtBr))
            .count();
        // `bytes` is spelled the same in both languages; anything much
        // beyond that means arms were left untranslated.
        let max_identical =
            crate::config::tuning_usize_in_range("i18n.max_untranslated_messages", 2, 0, 64);
        assert!(
            identical <= max_identical,
            "{identical} messages are byte-identical between en and pt-BR"
        );
    }

    /// Every compiled catalogue must answer for every message.
    #[test]
    fn every_compiled_locale_answers_for_every_message() {
        for lang in Language::compiled() {
            for msg in Message::all() {
                assert!(
                    !msg.text(*lang).is_empty(),
                    "empty text for {msg:?} in {}",
                    lang.as_tag()
                );
            }
        }
    }

    #[test]
    fn from_tag_accepts_posix_and_bcp47_shapes() {
        assert_eq!(Language::from_tag("pt_BR.UTF-8"), Some(Language::PtBr));
        assert_eq!(Language::from_tag("PT-br"), Some(Language::PtBr));
        assert_eq!(Language::from_tag("pt"), Some(Language::PtBr));
        assert_eq!(Language::from_tag("en-US"), Some(Language::En));
        assert_eq!(Language::from_tag("  en  "), Some(Language::En));
    }

    #[test]
    fn from_tag_rejects_locale_absent_from_this_build() {
        // `xx` is not a real language and can never be compiled in.
        assert_eq!(Language::from_tag("xx"), None);
    }

    #[test]
    fn from_tag_rejects_malformed_input() {
        assert_eq!(Language::from_tag("not a tag at all"), None);
        assert_eq!(Language::from_tag(""), None);
    }

    #[test]
    fn primary_subtag_reduces_region_and_encoding() {
        assert_eq!(primary_subtag("pt-BR"), "pt");
        assert_eq!(primary_subtag("pt_BR.UTF-8"), "pt");
        assert_eq!(primary_subtag("EN"), "en");
        assert_eq!(primary_subtag("es"), "es");
        assert_eq!(primary_subtag("zh-Hant-TW"), "zh");
    }

    #[test]
    fn normalise_locale_string_drops_encoding_and_modifier() {
        assert_eq!(normalise_locale_string(" pt_BR.UTF-8 "), "pt-BR");
        assert_eq!(normalise_locale_string("de_DE@euro"), "de-DE");
    }

    #[test]
    fn compiled_tags_always_lists_the_baseline() {
        let tags = Language::compiled_tags();
        assert!(tags.contains("en"), "missing en in {tags}");
        assert!(tags.contains("pt-BR"), "missing pt-BR in {tags}");
    }

    #[test]
    fn detect_system_language_never_panics() {
        // The result depends on the host, so only the total behaviour
        // is asserted: a compiled locale comes back, or English does.
        let resolved = detect_system_language();
        assert!(Language::compiled().contains(&resolved));
    }
}