// Copyright 2026 VKrishna04 // SPDX-License-Identifier: Apache-2.0 // Internationalisation: the fixed chrome of dev-prune's own output, in the language the // user asked for. // // Deliberately bounded, and the boundary is the whole design. Translated: section // headings, the summary lines, and the group titles in the configurator — the words that // repeat on every run and carry no information a script would parse. Never translated: // `--json`, exit codes, flag names, config keys, adapter names, and the sentence a // lockfile refusal prints. Those are a contract or a diagnosis; a bug report quoting a // translated refusal is a bug report nobody upstream can read, and a `--json` document // whose strings move with `LANG` is not a document. // // English is the source of truth. Every other catalogue is overlaid on top of it, so a // key a translator has not reached yet prints in English rather than printing its own // name — a half-finished translation degrades to the original instead of to gibberish. // // Adding a language is one JSON file and one line in [`CATALOGUES`]. See // `docs/TRANSLATIONS.md`. use std::collections::BTreeMap; use std::sync::OnceLock; use serde::Deserialize; use crate::constants; /// Every catalogue compiled into the binary. /// /// The only list of languages there is: the code, the names and the review status all /// come out of the file's own `_meta` block, so adding a language cannot half-happen by /// updating one list and not the other. const CATALOGUES: &[&str] = &[ include_str!("locales/en.json"), include_str!("locales/hi.json"), include_str!("locales/te.json"), include_str!("locales/ta.json"), include_str!("locales/kn.json"), include_str!("locales/ml.json"), include_str!("locales/bn.json"), include_str!("locales/mr.json"), include_str!("locales/gu.json"), include_str!("locales/pa.json"), include_str!("locales/sa.json"), include_str!("locales/zh.json"), ]; /// What a catalogue says about itself. #[derive(Debug, Clone, Deserialize)] pub struct Meta { /// The IETF subtag the config key and `DEV_PRUNE_LANG` take. pub code: String, /// The language's name in English, for the moment the choice is confirmed. pub english_name: String, /// The language's name in itself, for the person making the choice. pub native_name: String, /// Whether a native speaker has read this file through. /// /// Recorded rather than assumed, and said out loud where the language is chosen. A /// translation nobody has checked is still worth shipping — it is how the first /// speaker of that language finds the mistakes — but saying so is the difference /// between an invitation and a claim. pub reviewed: bool, } /// One language's strings, plus what it says about itself. #[derive(Debug, Clone, Deserialize)] struct Catalogue { #[serde(rename = "_meta")] meta: Meta, #[serde(flatten)] strings: BTreeMap, } /// The catalogues that parsed, in the order of [`CATALOGUES`]. /// /// A file that does not parse is dropped rather than panicked on: a malformed /// translation should cost that translation, not the run. `catalogues_all_parse` is what /// stops one reaching a release. fn parsed() -> &'static Vec { static PARSED: OnceLock> = OnceLock::new(); PARSED.get_or_init(|| { CATALOGUES .iter() .filter_map(|raw| serde_json::from_str::(raw).ok()) .collect() }) } /// The strings actually in use: English, with the chosen language laid over the top. static ACTIVE: OnceLock> = OnceLock::new(); /// Build the merged table for one language code. fn merge(code: &str) -> BTreeMap { let mut merged = parsed() .iter() .find(|c| c.meta.code == constants::DEFAULT_LANGUAGE) .map(|c| c.strings.clone()) .unwrap_or_default(); if code != constants::DEFAULT_LANGUAGE && let Some(chosen) = parsed().iter().find(|c| c.meta.code == code) { // Only keys the translator actually filled in. An empty string is a key they // opened and left, and falling back is better than printing nothing at all. for (key, value) in &chosen.strings { if !value.trim().is_empty() { merged.insert(key.clone(), value.clone()); } } } merged } /// Choose the language for this process. /// /// Resolution order, highest first: /// /// 1. `DEV_PRUNE_LANG`, which governs one invocation and is what a script or a CI job /// sets when it wants a known language whatever the machine is configured for. /// 2. the `language` setting, which is the durable answer for this user. /// 3. English. /// /// The operating system's own locale is deliberately *not* consulted. A machine set to /// Hindi has said nothing about what language it wants its build tools in, and a user /// who has never asked for a translation should not be given a partial one by a /// variable they did not set. /// /// Idempotent, and the first call wins — later calls are ignored, so a command that /// re-reads the registry cannot change the language halfway through its own output. pub fn init(configured: Option<&str>) { let requested = std::env::var(constants::ENV_LANGUAGE) .ok() .map(|v| v.trim().to_string()) .filter(|v| !v.is_empty()) .or_else(|| configured.map(str::to_string)) .unwrap_or_else(|| constants::DEFAULT_LANGUAGE.to_string()); // An unknown code is English rather than an error. This runs before the command // does, and refusing to start because of a typo in a cosmetic setting would be a // worse failure than the one it reports. let code = if language(&requested).is_some() { requested } else { constants::DEFAULT_LANGUAGE.to_string() }; let _ = ACTIVE.set(merge(&code)); } /// One translated string. /// /// Falls back to the key itself, which is why every call site passes a literal: a /// missing key then prints something a maintainer can grep for rather than an empty /// line. In practice `catalogues_cover_english` makes that unreachable. pub fn t(key: &'static str) -> &'static str { ACTIVE .get_or_init(|| merge(constants::DEFAULT_LANGUAGE)) .get(key) .map(String::as_str) .unwrap_or(key) } /// A translated string with `{name}` placeholders filled in. /// /// Runtime substitution rather than `format!` because the template is chosen at runtime /// and `format!` needs a literal. Placeholders are named, not positional, so a /// translator may reorder them — which some of these languages require. pub fn tf(key: &'static str, args: &[(&str, &str)]) -> String { let mut out = t(key).to_string(); for (name, value) in args { out = out.replace(&format!("{{{name}}}"), value); } out } /// What a language code resolves to, or `None` if this binary has no catalogue for it. pub fn language(code: &str) -> Option<&'static Meta> { parsed() .iter() .find(|c| c.meta.code == code) .map(|c| &c.meta) } /// Every language as `(code, native name)`, for the configurator's picker. /// /// Pairs rather than bare codes because `te` is not a word anybody reads: the row has to /// be legible to the person the translation is *for*, who may well not know the subtag. /// `&'static` so the picker can hold it in a `Copy` control without knowing where it came /// from. pub fn choices() -> &'static [(&'static str, &'static str)] { static CHOICES: OnceLock> = OnceLock::new(); CHOICES.get_or_init(|| { parsed() .iter() .map(|c| (c.meta.code.as_str(), c.meta.native_name.as_str())) .collect() }) } /// `en English · hi हिन्दी · te తెలుగు · …`, for the error an unknown code earns. pub fn catalogue_line() -> String { choices() .iter() .map(|(code, native)| format!("{code} {native}")) .collect::>() .join(" · ") } #[cfg(test)] mod tests { use super::*; /// A catalogue that does not parse is silently dropped at runtime, so this is the /// only thing standing between a stray comma and a release that quietly speaks /// English to everyone who asked for Telugu. #[test] fn catalogues_all_parse() { assert_eq!( parsed().len(), CATALOGUES.len(), "a locale file failed to parse; every entry in CATALOGUES must be valid JSON \ with a _meta block" ); } /// English defines the key set. A translation with a key English does not have is a /// string nothing prints — usually a typo in the key, which is invisible at runtime /// because the merge simply ignores it. #[test] fn catalogues_cover_english() { let english: Vec<&String> = parsed() .iter() .find(|c| c.meta.code == constants::DEFAULT_LANGUAGE) .expect("en.json must exist") .strings .keys() .collect(); for catalogue in parsed() { for key in catalogue.strings.keys() { assert!( english.contains(&key), "{}.json has key `{key}`, which en.json does not", catalogue.meta.code ); } } } /// Codes are the value `devp config set language` takes, so two catalogues claiming /// one code would make the setting ambiguous. #[test] fn codes_are_unique_and_start_with_english() { let mut seen = std::collections::BTreeSet::new(); for (code, _) in choices() { assert!(seen.insert(*code), "duplicate language code `{code}`"); } assert_eq!( choices().first().map(|(code, _)| *code), Some(constants::DEFAULT_LANGUAGE) ); } /// Every catalogue names itself in its own language, which is the only string the /// picker can show somebody who cannot read the English name. #[test] fn every_catalogue_names_itself() { for (code, _) in choices() { let meta = language(code).expect("choices() only lists catalogues that parsed"); assert!(!meta.english_name.trim().is_empty(), "{code}"); assert!(!meta.native_name.trim().is_empty(), "{code}"); } } #[test] fn unknown_language_is_not_supported() { assert!(language("en").is_some()); assert!(language("te").is_some()); assert!(language("xx").is_none()); assert!(language("EN").is_none()); } #[test] fn placeholders_are_filled_by_name() { // The English template is the one under test; a translation may reorder them. let filled = tf("run.freed", &[("size", "1.2 GB"), ("count", "7")]); assert!(filled.contains("1.2 GB"), "{filled}"); assert!(filled.contains('7'), "{filled}"); assert!(!filled.contains('{'), "{filled}"); } /// The reason the catalogues are merged rather than swapped: an unfinished /// translation prints English, never the raw key. #[test] fn an_untranslated_key_falls_back_to_english() { let english = merge(constants::DEFAULT_LANGUAGE); for (code, _) in choices() { for (key, value) in merge(code) { assert!(!value.trim().is_empty(), "`{code}` has an empty `{key}`"); assert!( english.contains_key(&key), "`{code}` invented the key `{key}`" ); } } } }