GitCorner

Code

ossartcraftphotocraft🌐
856f865cf98d
//! UI localisation. Strings in code stay English and are the default lookup keys; the craft-i18n
//! catalogs map them to display text at render time. Command ids, menu paths used for logic, the
//! control channel, the CLI and MCP never see translated text, so agents and scripts are
//! unaffected. A string without a translation is shown in English, and a missing translation never
//! fails a build or a release. A few tests check named rows of the pinned catalogs, so moving
//! `craft-i18n.rev` to a commit that drops one fails that test until it is updated.
//!
//! The catalogs live in [storytold/craft-i18n](https://github.com/storytold/craft-i18n)
//! (`locales/<code>/common.tsv`, shared by the Crafting Apps, and `photocraft.tsv`), not in this
//! repository. `build.rs` embeds them from `CRAFT_I18N_DIR` (CI and releases check out the commit
//! in `craft-i18n.rev`); without it the build is English only. Lookup, fallback (PhotoCraft's rows
//! over shared ones), plural forms (CLDR) and language names are the `craft-i18n` crate's
//! (craft-libs). Which languages are offered, how the system locale picks one, reading direction
//! and `{name}` placeholders stay here.
//!
//! # Adding or changing a translation
//! In craft-i18n: add rows to `locales/<code>/photocraft.tsv` (its `docs/integration.md`). They
//! show here once `craft-i18n.rev` moves to a commit that has them. A feature PR here adds the
//! English only; `cargo xtask i18n-report` lists what each language lacks.
//!
//! # Adding a language
//! 1. craft-i18n gets `locales/<code>/photocraft.tsv` with its `@id language.name` row.
//! 2. Add one row to [`LANGUAGES`].
//!
//! That is all: the Preferences dropdown and the system-locale match pick it up from the registry.
//! A right-to-left language (Arabic, Hebrew, Persian, Urdu, see [`Lang::dir`]) also mirrors the
//! window's chrome ([`crate::direction`]).
//!
//! # Looking strings up
//! - [`tr`]: a plain string. [`tr_ctx`]: when one English word needs different translations.
//! - [`tr_id`]: a command-id keyed string with the English label as fallback (menu items), so a
//!   translation survives rewording of the English text and can differ per command.
//! - [`trn`]: plural-aware (`{n}` is filled in). [`fmt`]: fill `{name}` placeholders after [`tr`];
//!   translators may reorder placeholders freely.

mod system;

pub use system::{decimal_separator, system_lang};

use std::cell::Cell;
use std::collections::HashMap;
use std::sync::{LazyLock, OnceLock};

use craft_i18n::I18n;

include!(concat!(env!("OUT_DIR"), "/craft_i18n.rs"));

/// The embedded catalogs, offering exactly the languages in [`LANGUAGES`]. Built on first use; a
/// locale is parsed on its first lookup.
static I18N: LazyLock<I18n> = LazyLock::new(|| {
    let offered: Vec<&str> = LANGUAGES.iter().map(|l| l.code).collect();
    let (i18n, problems) = I18n::new(CRAFT_I18N, &offered);
    for problem in problems {
        log::warn!("interface catalogs: {problem}");
    }
    i18n
});

/// The same catalogs for the craft framework's components, which take their words from the
/// framework's own craft-i18n through the `Host`.
pub(crate) fn framework_i18n() -> &'static std::sync::Arc<craft::i18n::I18n> {
    static FRAMEWORK: LazyLock<std::sync::Arc<craft::i18n::I18n>> = LazyLock::new(|| {
        let offered: Vec<&str> = LANGUAGES.iter().map(|l| l.code).collect();
        std::sync::Arc::new(craft::i18n::I18n::new(CRAFT_I18N, &offered).0)
    });
    &FRAMEWORK
}

/// One UI language PhotoCraft offers, when its catalogs are embedded: what the app needs beyond
/// them. Its name and translations come from craft-i18n.
pub struct LangInfo {
    /// BCP 47 code, lowercase (`ja`, `zh-hans`, `pt-br`, `sr-latn`). Also the `interface.language`
    /// value and the craft-i18n locale.
    pub code: &'static str,
    /// Does the catalog cover every menu string? (`cargo xtask i18n-report` lists what it lacks)
    pub complete_menus: bool,
}

/// A script's reading direction.
pub use craft::i18n::Direction as Dir;

/// How many languages [`LANGUAGES`] lists.
const LANGUAGE_COUNT: usize = 35;

/// The registry. English first: it is the fallback and the source language. Plural forms follow
/// each language's CLDR rules (the craft-i18n crate).
pub static LANGUAGES: [LangInfo; LANGUAGE_COUNT] = [
    LangInfo { code: "en", complete_menus: false },
    LangInfo { code: "ja", complete_menus: true },
    LangInfo { code: "zh-hans", complete_menus: true },
    // Traditional Chinese in the vocabulary used in Taiwan; `zh-TW`, `zh-HK`, `zh-MO` and `zh-Hant-*`
    // locales all resolve here (see `candidates`).
    LangInfo { code: "zh-hant", complete_menus: true },
    LangInfo { code: "es", complete_menus: true },
    LangInfo { code: "ru", complete_menus: true },
    LangInfo { code: "uk", complete_menus: true },
    // Serbian (Latin script, Ekavian). `sr-RS`, `sr-Latn-*` and `sr_RS@latin` resolve here; so do
    // plain `sr` and Cyrillic `sr` locales, which read Latin rather than English (see `candidates`).
    // Saved as `sr` before the catalogs moved to craft-i18n (the engine migrates it).
    LangInfo { code: "sr-latn", complete_menus: true },
    // Bosnian (Latin script, Ijekavian). `bs-BA`, `bs-Latn-*` and `bs_BA.UTF-8` resolve here; so do
    // Cyrillic `bs` locales, which read Latin rather than English.
    LangInfo { code: "bs", complete_menus: true },
    LangInfo { code: "cs", complete_menus: true },
    LangInfo { code: "fr", complete_menus: true },
    LangInfo { code: "id", complete_menus: true },
    LangInfo { code: "ko", complete_menus: true },
    LangInfo { code: "pl", complete_menus: true },
    LangInfo { code: "de", complete_menus: true },
    // Brazilian Portuguese; `pt`, `pt-BR` and `pt-PT` locales all resolve here (see `candidates`).
    LangInfo { code: "pt-br", complete_menus: true },
    LangInfo { code: "el", complete_menus: true },
    // Dutch; `nl-NL` and `nl-BE` locales both resolve here.
    LangInfo { code: "nl", complete_menus: true },
    LangInfo { code: "it", complete_menus: true },
    // Hungarian: a count takes the singular noun ("3 réteg"), so both plural forms read the same.
    LangInfo { code: "hu", complete_menus: true },
    // Turkish; `tr`, `tr-TR` and `tr_TR` locales resolve here.
    LangInfo { code: "tr", complete_menus: true },
    // Azerbaijani (Latin script); regional and explicit Latin-script tags resolve here.
    LangInfo { code: "az", complete_menus: true },
    // Vietnamese; `vi-VN` resolves here.
    LangInfo { code: "vi", complete_menus: true },
    // Thai; `th`, `th-TH` and `th_TH.UTF-8` locales resolve here. Thai has no plural inflection.
    LangInfo { code: "th", complete_menus: true },
    // Hindi; `hi`, `hi-IN` locales resolve here.
    LangInfo { code: "hi", complete_menus: false },
    // Arabic (Modern Standard); `ar-SA`, `ar-EG` and the other regional locales resolve here. The
    // chrome mirrors right to left (`Lang::dir`), and egui lays each label out right to left.
    LangInfo { code: "ar", complete_menus: true },
    // Swedish; `sv-SE` and `sv-FI` locales resolve here.
    LangInfo { code: "sv", complete_menus: true },
    // Finnish; `fi-FI` resolves here (Swedish in Finland, `sv-FI`, stays Swedish). The partitive
    // singular follows any number but 1 ("1 taso", "2 tasoa").
    LangInfo { code: "fi", complete_menus: true },
    // Danish; `da-DK` and the other `da-*` locales resolve here.
    LangInfo { code: "da", complete_menus: true },
    // Norwegian Bokmål; `nb-NO`, and the macrolanguage `no` and Nynorsk `nn` from POSIX locales,
    // resolve here (see `candidates`).
    LangInfo { code: "nb", complete_menus: true },
    // Hebrew; `he-il` and `he_IL` resolve here. The chrome mirrors right to left (`Lang::dir`),
    // like Arabic. Its `two` plural form repeats `other`, as modern Hebrew software UI does.
    LangInfo { code: "he", complete_menus: true },
    // Urdu; written right to left like Arabic (`Lang::dir`).
    LangInfo { code: "ur", complete_menus: true },
    // Romanian; `ro-RO` and `ro-MD` resolve here.
    LangInfo { code: "ro", complete_menus: true },
    // Tamil; `ta-IN`, `ta-LK` and `ta_IN.UTF-8` resolve here.
    LangInfo { code: "ta", complete_menus: true },
    // Georgian: nouns stay singular after a numeral (`შრე: 5`, `5 შრე`), so both plural forms read
    // the same.
    LangInfo { code: "ka", complete_menus: true },
];

/// Per language of [`LANGUAGES`], PhotoCraft's own catalog rows as written (escaped): (context,
/// source) to translation, read on first use ([`Lang::owns`]).
static OWN_ROWS: [OnceLock<HashMap<(&'static str, &'static str), &'static str>>; LANGUAGE_COUNT] = [const { OnceLock::new() }; LANGUAGE_COUNT];

/// A language the UI can be shown in: English, or one of [`LANGUAGES`] whose catalogs are
/// embedded.
#[derive(Clone, Copy)]
pub struct Lang {
    lang: craft_i18n::Lang,
    /// The catalogs it is looked up in: the embedded ones ([`I18N`]), or a test fixture's.
    catalogs: Option<&'static I18n>,
}

impl std::fmt::Debug for Lang {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Lang({})", self.code())
    }
}

impl PartialEq for Lang {
    fn eq(&self, other: &Self) -> bool {
        self.code() == other.code()
    }
}

impl Eq for Lang {}

impl Lang {
    pub const EN: Lang = Lang { lang: craft_i18n::Lang::EN, catalogs: None };

    fn i18n(self) -> &'static I18n {
        self.catalogs.unwrap_or_else(|| LazyLock::force(&I18N))
    }

    fn info(self) -> Option<&'static LangInfo> {
        let code = self.code();
        LANGUAGES.iter().find(|l| l.code == code)
    }

    pub fn code(self) -> &'static str {
        self.i18n().code(self.lang)
    }

    /// A language by its exact code (any case): one of [`LANGUAGES`] whose catalogs are embedded.
    pub fn from_code(code: &str) -> Option<Lang> {
        let info = LANGUAGES.iter().find(|l| l.code.eq_ignore_ascii_case(code))?;
        I18N.from_code(info.code).map(|lang| Lang { lang, catalogs: None })
    }

    /// Resolve the `interface.language` preference: a language code, or `auto` (and anything
    /// unknown, e.g. a code from a newer version) to follow the system locale.
    pub fn from_pref(pref: &str) -> Lang {
        if pref.eq_ignore_ascii_case("auto") {
            return system_lang();
        }
        Lang::from_code(pref).or_else(|| lang_from_tag(pref)).unwrap_or_else(system_lang)
    }

    /// Every language the interface can be shown in: [`LANGUAGES`] in order, those whose catalogs
    /// are embedded (English alone in a build without craft-i18n).
    pub fn all() -> impl Iterator<Item = Lang> {
        LANGUAGES.iter().filter_map(|l| Lang::from_code(l.code))
    }

    /// Every registered language in the order a picker lists them: English first (the source
    /// language and the fallback), then the rest by their own name with accents folded, so
    /// Čeština sits under C and Türkçe under T rather than after Z. Names in other scripts follow
    /// the Latin ones in code point order: Greek, Cyrillic, then the CJK languages.
    pub fn for_picker() -> Vec<Lang> {
        let mut rest: Vec<Lang> = Lang::all().filter(|l| l.code() != "en").collect();
        rest.sort_by_cached_key(|l| name_sort_key(l.name()));
        std::iter::once(Lang::EN).chain(rest).collect()
    }

    /// The language's name in itself (its `@id language.name` row), shown in the Preferences
    /// dropdown.
    pub fn name(self) -> &'static str {
        self.i18n().name(self.lang)
    }

    /// Does this language's catalog claim to cover every menu string and `tl!` literal?
    pub fn complete_menus(self) -> bool {
        self.info().is_some_and(|l| l.complete_menus)
    }

    /// The language's reading direction.
    pub fn dir(self) -> Dir {
        craft::i18n::direction(self.code())
    }

    /// Whether `translated`, the lookup's text for (`context`, `source`), comes from PhotoCraft's
    /// own catalog (`photocraft.tsv`, not the shared `common.tsv`). The shared catalog's `@id` rows
    /// are keyed by the other apps' command ids, which can name another command, so command-id
    /// lookups ask this; every `@id` row PhotoCraft had is in its own catalog. Comparing the text,
    /// not only the key, keeps a shared row out when craft-i18n skipped a malformed own row. A test
    /// fixture has no shared catalog: its rows are its own.
    fn owns(self, context: &str, source: &str, translated: &str) -> bool {
        if let Some(fixture) = self.catalogs {
            return fixture.get(self.lang, context, source) == Some(translated);
        }
        let code = self.code();
        let Some(slot) = LANGUAGES.iter().position(|l| l.code == code).and_then(|i| OWN_ROWS.get(i)) else { return false };
        let rows: &HashMap<(&str, &str), &str> = slot.get_or_init(|| {
            app_catalog(code)
                .lines()
                .filter(|l| !l.starts_with('#'))
                .filter_map(|l| {
                    let mut columns = l.split('\t');
                    Some(((columns.next()?, columns.next()?), columns.next()?))
                })
                .collect()
        });
        let escape = |s: &str| s.replace('\\', "\\\\").replace('\n', "\\n").replace('\t', "\\t");
        rows.get(&(escape(context).as_str(), escape(source).as_str())).is_some_and(|own| *own == escape(translated))
    }
}

impl Lang {
    /// The embedded catalog texts this language reads, the shared one then PhotoCraft's; none for
    /// English. For checks that the interface fonts draw every translation.
    #[cfg(test)]
    pub(crate) fn catalog_texts(self) -> impl Iterator<Item = &'static str> {
        let code = self.code();
        CRAFT_I18N.iter().filter(move |(c, ..)| c.eq_ignore_ascii_case(code)).flat_map(|(_, shared, app)| [*shared, *app])
    }
}

/// PhotoCraft's own embedded catalog text (`photocraft.tsv`) in the locale `code`; empty when
/// there is none.
fn app_catalog(code: &str) -> &'static str {
    CRAFT_I18N.iter().find(|(c, ..)| c.eq_ignore_ascii_case(code)).map_or("", |(_, _, app)| *app)
}

/// Whether this build embeds the craft-i18n catalogs (`CRAFT_I18N_DIR` was set). Without them the
/// interface is English only; tests that need a translation skip with a note.
pub fn catalogs_embedded() -> bool {
    !CRAFT_I18N.is_empty()
}

/// `name` lowercased with the Latin accents that occur in language names folded away, so a
/// byte-wise sort reads alphabetically. Other scripts are left as they are.
fn name_sort_key(name: &str) -> String {
    name.chars()
        .flat_map(char::to_lowercase)
        .map(|c| match c {
            'à'..='å' | 'ā' | 'ă' | 'ą' => 'a',
            'ç' | 'ć' | 'č' => 'c',
            'è'..='ë' | 'ē' | 'ě' | 'ę' | 'ế' | 'ệ' => 'e',
            'ì'..='ï' | 'ī' => 'i',
            'ñ' | 'ń' | 'ň' => 'n',
            'ò'..='ö' | 'ø' | 'ő' => 'o',
            'ś' | 'š' => 's',
            'ù'..='ü' | 'ū' | 'ů' | 'ű' => 'u',
            'ý' | 'ÿ' => 'y',
            'ź' | 'ż' | 'ž' => 'z',
            c => c,
        })
        .collect()
}

/// Candidate language codes for a locale tag, most specific first: `zh_TW.UTF-8` →
/// `zh-tw`, `zh-hant`, `zh`.
fn candidates(tag: &str) -> Vec<String> {
    let base = tag.split(['.', '@']).next().unwrap_or("").replace('_', "-").to_ascii_lowercase();
    let parts: Vec<&str> = base.split('-').filter(|p| !p.is_empty()).collect();
    let Some(&primary) = parts.first() else { return Vec::new() };
    let mut out = Vec::new();
    for n in (1..=parts.len()).rev() {
        out.push(parts[..n].join("-"));
    }
    if primary == "zh" && !parts.iter().any(|p| matches!(*p, "hans" | "hant")) {
        // Chinese by region when no script is given.
        let script = if parts.iter().any(|p| matches!(*p, "tw" | "hk" | "mo")) { "zh-hant" } else { "zh-hans" };
        out.insert(out.len() - 1, script.to_string());
    }
    if primary == "pt" && !out.iter().any(|c| c == "pt-br") {
        // The only Portuguese catalog is Brazilian; other regions use it rather than English.
        out.insert(out.len() - 1, "pt-br".to_string());
    }
    if primary == "sr" && !out.iter().any(|c| c == "sr-latn") {
        // The only Serbian catalog is Latin (`sr-latn`). Plain, regional (`sr-RS`, `sr-ME`) and
        // Cyrillic (`sr-Cyrl-RS`) tags read it rather than English, as when it was PhotoCraft's
        // `sr` catalog; craft-i18n's own matching never takes `sr` to a script it doesn't name.
        out.insert(out.len() - 1, "sr-latn".to_string());
    }
    if matches!(primary, "no" | "nn") && !out.iter().any(|c| c == "nb") {
        // The only Norwegian catalog is Bokmål; the macrolanguage code and Nynorsk use it rather
        // than English.
        out.insert(out.len() - 1, "nb".to_string());
    }
    out
}

/// The registered language for a locale tag such as `ja_JP.UTF-8`, `ja-JP`, `zh-TW`; `None` if
/// the language isn't supported. `C`/`POSIX` mean English.
pub fn lang_from_tag(tag: &str) -> Option<Lang> {
    let cands = candidates(tag);
    if matches!(cands.first().map(String::as_str), Some("c" | "posix")) {
        return Some(Lang::EN);
    }
    cands.iter().find_map(|c| Lang::from_code(c))
}

thread_local! {
    // Independent app/test threads must not change each other's drawing language.
    static CURRENT: Cell<Lang> = const { Cell::new(Lang::EN) };
}

/// Set the UI language for drawing (the shell calls this once per frame from the preference), so
/// widgets can translate without every call site carrying a language around.
pub fn set_current(lang: Lang) {
    CURRENT.set(lang);
}

/// The language the UI is drawn in.
pub fn current() -> Lang {
    CURRENT.get()
}

/// Temporarily draw in another language, restoring the previous one even on unwinding.
/// Preferences previews use this without changing the saved setting or other dialogs.
pub fn with_language<R>(lang: Lang, draw: impl FnOnce() -> R) -> R {
    let _restore = language_scope(lang);
    draw()
}

/// Keep the language active until this guard is dropped on the drawing thread.
#[must_use]
pub fn language_scope(lang: Lang) -> impl Drop {
    struct Restore {
        previous: Lang,
        _thread: std::marker::PhantomData<std::rc::Rc<()>>,
    }
    impl Drop for Restore {
        fn drop(&mut self) {
            set_current(self.previous);
        }
    }
    let restore = Restore { previous: current(), _thread: std::marker::PhantomData };
    set_current(lang);
    restore
}

/// Apply a committed language to this context. Font caches are rebuilt only on a language
/// change, so Han glyphs follow the selected script even when the previous font covered them.
pub fn sync_context(ctx: &egui::Context, language: &str) {
    let lang = Lang::from_pref(language);
    set_current(lang);
    let id = egui::Id::unique("photocraft-ui-language");
    let changed = ctx.data(|data| data.get_temp::<Lang>(id) != Some(lang));
    if changed {
        ctx.data_mut(|data| data.insert_temp(id, lang));
        crate::theme::install_fonts(ctx);
        ctx.request_repaint();
    }
}

/// Does `lang` have a catalog entry for this plain string? (English never does: it is the source.)
pub fn has(lang: Lang, s: &str) -> bool {
    lang.i18n().get(lang.lang, "", s).is_some()
}

/// Translate an English UI string into the current language ([`tr`] with [`current`]).
pub fn t(s: &str) -> &str {
    tr(current(), s)
}

/// Translate an English UI string; unknown strings come back unchanged.
pub fn tr(lang: Lang, s: &str) -> &str {
    lang.i18n().t(lang.lang, s)
}

/// Like [`tr`], for an English string that needs a disambiguating `context`.
pub fn tr_ctx<'a>(lang: Lang, context: &str, s: &'a str) -> &'a str {
    lang.i18n().tc(lang.lang, context, s)
}

/// A string keyed by its command id, falling back to the translation of the English `label`. Only
/// PhotoCraft's own `@id` rows count ([`own_id`]).
pub fn tr_id<'a>(lang: Lang, id: &str, label: &'a str) -> &'a str {
    if own_id(lang, id, label) { lang.i18n().tid(lang.lang, id, label) } else { tr(lang, label) }
}

/// Whether `lang` has PhotoCraft's own `@id` row for `id` ([`Lang::owns`]: command ids are each
/// app's own) and it keeps the `{placeholders}` and trailing `…` of the English `label`. craft-i18n
/// can't check that, because an `@id` row's source is the id, so a row that doesn't is skipped
/// here and the label's translation shows instead.
fn own_id(lang: Lang, id: &str, label: &str) -> bool {
    lang.i18n().get(lang.lang, "@id", id).is_some_and(|translated| lang.owns("@id", id, translated) && same_shape(translated, label))
}

/// Whether `translated` has the `{placeholders}` (in any order) and the trailing `…` of `english`,
/// the check craft-i18n makes on every row whose source is English text, and no `{` left open or
/// `}` without its `{`.
fn same_shape(translated: &str, english: &str) -> bool {
    let placeholders = |text: &str| -> Option<Vec<String>> {
        let mut names = text.split('{').skip(1).map(|p| p.split_once('}').map(|(name, _)| name.to_owned())).collect::<Option<Vec<_>>>()?;
        if text.matches('}').count() != names.len() {
            return None;
        }
        names.sort_unstable();
        Some(names)
    };
    translated.ends_with('…') == english.ends_with('…') && placeholders(translated).is_some_and(|names| Some(names) == placeholders(english))
}

/// Fill `{name}` placeholders. Unknown placeholders are left as written.
pub fn fmt(template: &str, args: &[(&str, &str)]) -> String {
    let mut out = template.to_string();
    for (k, v) in args {
        out = out.replace(&format!("{{{k}}}"), v);
    }
    out
}

/// A plural-aware message: `one`/`other` are the English forms (with `{n}` where the count goes).
/// The form is the language's CLDR category; `{n}` is written in `0`–`9` without grouping or
/// isolate marks, as PhotoCraft always has.
pub fn trn(lang: Lang, n: u64, one: &str, other: &str) -> String {
    lang.i18n().trn_plain(lang.lang, n, one, other)
}

/// A test language whose PhotoCraft catalog is `source` (catalog format), so tests of lookup code
/// don't depend on the embedded catalogs' wording. `code` picks the CLDR plural rules.
#[cfg(test)]
pub(crate) fn fixture_lang(code: &'static str, source: &'static str) -> Lang {
    let embedded: &'static craft_i18n::Embedded = Box::leak(Box::new([(code, "", source)]));
    let (i18n, _) = I18n::new(embedded, &[code]);
    let i18n: &'static I18n = Box::leak(Box::new(i18n));
    let lang = i18n.from_code(code).unwrap_or(craft_i18n::Lang::EN);
    Lang { lang, catalogs: Some(i18n) }
}

/// For a test that needs the embedded catalogs: `false`, with a note, when none were embedded
/// (`CRAFT_I18N_DIR` unset), so the test can skip; the interface is then English only.
#[cfg(test)]
pub(crate) fn needs_catalogs() -> bool {
    if !catalogs_embedded() {
        eprintln!("skipped: built without craft-i18n (set CRAFT_I18N_DIR to a craft-i18n checkout); the interface is English only");
    }
    catalogs_embedded()
}

#[cfg(test)]
mod tests;

#[cfg(test)]
mod live_tests;