a02d892f831f
localization.rs
//! Language selection and source-language fallback for UI strings.
#[path = "../locales/pt-BR/mod.rs"]
mod pt_br;
use std::cell::Cell;
thread_local! {
static CURRENT_LANGUAGE: Cell<Language> = const { Cell::new(Language::English) };
}
/// A language supported by the UI.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum Language {
#[default]
#[serde(rename = "en")]
English,
#[serde(rename = "pt-BR")]
PortugueseBrazil,
}
impl Language {
/// All supported languages, in the order they are shown in the language menu.
pub const ALL: [Self; 2] = [Self::English, Self::PortugueseBrazil];
/// Stable language tag used in preferences and control commands.
pub const fn id(self) -> &'static str {
match self {
Self::English => "en",
Self::PortugueseBrazil => "pt-BR",
}
}
/// English source name of the language; translate it with `text` for display.
pub const fn native_name(self) -> &'static str {
match self {
Self::English => "English",
Self::PortugueseBrazil => "Portuguese (Brazil)",
}
}
pub fn parse(tag: &str) -> Option<Self> {
Self::ALL.into_iter().find(|language| language.id().eq_ignore_ascii_case(tag.trim()))
}
/// Rewrites the decimal point of a rendered number for this language.
pub fn localize_decimal(self, number: &str) -> String {
match self {
Self::English => number.to_owned(),
Self::PortugueseBrazil => number.replace('.', ","),
}
}
/// Translates a UI string, falling back to its English source when no translation exists.
pub fn text(self, source: &str) -> &str {
match self {
Self::English => source,
Self::PortugueseBrazil => pt_br::translate(source).unwrap_or(source),
}
}
}
/// Sets the language used by text widgets on this thread for the duration of a UI frame.
pub fn enter(language: Language) -> LanguageScope {
let previous = CURRENT_LANGUAGE.with(|current| current.replace(language));
LanguageScope(previous)
}
/// The language selected for the current UI frame.
pub fn current_language() -> Language {
CURRENT_LANGUAGE.with(Cell::get)
}
/// Translates a source string using the language selected for the current UI frame.
pub fn text(source: &str) -> &str {
current_language().text(source)
}
/// Translates an engine error message for display. Messages are matched against the catalog's
/// error templates and their embedded values are carried over; text that matches no template is
/// returned unchanged, so low-level library errors stay in English.
pub fn error_text(message: &str) -> String {
error_text_in(current_language(), message, 0)
}
const MAX_ERROR_DEPTH: usize = 4;
fn error_text_in(language: Language, message: &str, depth: usize) -> String {
let templates: &[(&str, &str)] = match language {
Language::English => &[],
Language::PortugueseBrazil => pt_br::ERROR_TEMPLATES,
};
let mut best: Option<(usize, &str, Vec<(String, String)>)> = None;
for (template, translation) in templates {
if let Some((weight, captures)) = match_template(template, message)
&& best.as_ref().is_none_or(|(w, ..)| weight > *w)
{
best = Some((weight, translation, captures));
}
}
let Some((_, translation, captures)) = best else { return message.to_owned() };
let captures: Vec<(String, String)> = captures
.into_iter()
.map(|(name, value)| {
let value = if depth < MAX_ERROR_DEPTH { error_text_in(language, &value, depth + 1) } else { value };
(name, value)
})
.collect();
fill_captures(language, translation, &captures)
}
enum Piece<'a> {
Literal(String),
Field(&'a str),
}
fn split_template(template: &str) -> Vec<Piece<'_>> {
let mut pieces = Vec::new();
let mut literal = String::new();
let mut rest = template;
while let Some(ch) = rest.chars().next() {
if let Some(after) = rest.strip_prefix("{{") {
literal.push('{');
rest = after;
} else if let Some(after) = rest.strip_prefix("}}") {
literal.push('}');
rest = after;
} else if ch == '{'
&& let Some(end) = rest.find('}')
{
if !literal.is_empty() {
pieces.push(Piece::Literal(std::mem::take(&mut literal)));
}
pieces.push(Piece::Field(rest.get(1..end).unwrap_or_default()));
rest = rest.get(end + 1..).unwrap_or_default();
} else {
literal.push(ch);
rest = rest.get(ch.len_utf8()..).unwrap_or_default();
}
}
if !literal.is_empty() {
pieces.push(Piece::Literal(literal));
}
pieces
}
/// Matches `message` against `template`. Returns the template's literal length, used to prefer
/// the most specific template, and the captured values by placeholder name.
fn match_template(template: &str, message: &str) -> Option<(usize, Vec<(String, String)>)> {
let pieces = split_template(template);
let mut captures = Vec::new();
let mut pos = 0usize;
let mut weight = 0usize;
let mut index = 0usize;
while let Some(piece) = pieces.get(index) {
match piece {
Piece::Literal(text) => {
if !message.get(pos..)?.starts_with(text.as_str()) {
return None;
}
pos += text.len();
weight += text.len();
}
Piece::Field(name) => {
let rest = message.get(pos..)?;
let end = match pieces.get(index + 1) {
None => rest.len(),
Some(Piece::Literal(next)) if pieces.len() == index + 2 => {
if rest.len() < next.len() || !rest.ends_with(next.as_str()) {
return None;
}
rest.len() - next.len()
}
Some(Piece::Literal(next)) => rest.find(next.as_str())?,
Some(Piece::Field(_)) => return None,
};
if end == 0 {
return None;
}
let name = name.split(':').next().unwrap_or_default();
captures.push((name.to_owned(), rest.get(..end)?.to_owned()));
pos += end;
}
}
index += 1;
}
(pos == message.len() && weight > 0).then_some((weight, captures))
}
fn fill_captures(language: Language, translation: &str, captures: &[(String, String)]) -> String {
let mut out = String::with_capacity(translation.len());
for piece in split_template(translation) {
match piece {
Piece::Literal(text) => out.push_str(&text),
Piece::Field(field) => {
let name = field.split(':').next().unwrap_or_default();
match captures.iter().find(|(captured, _)| captured == name) {
Some((_, value)) if value.parse::<f64>().is_ok() => out.push_str(&language.localize_decimal(value)),
Some((_, value)) => out.push_str(value),
None => {
out.push('{');
out.push_str(field);
out.push('}');
}
}
}
}
}
out
}
/// Whether the Brazilian Portuguese catalog has an entry for `source`, even an identical one.
#[cfg(test)]
pub(crate) fn has_pt_br_entry(source: &str) -> bool {
pt_br::translate(source).is_some()
}
/// Guard that restores the previously active language when dropped.
pub struct LanguageScope(Language);
impl Drop for LanguageScope {
/// Restores the language that was active when the scope was created.
fn drop(&mut self) {
CURRENT_LANGUAGE.with(|language| language.set(self.0));
}
}
/// One formatting argument, kept as a reference and rendered only when the template asks for it.
///
/// The template is only known at run time, so the format specifier is too: the formatter reads a
/// `:.N` precision from it and renders the value with that precision.
pub struct Arg<'a> {
value: &'a dyn std::fmt::Display,
}
impl<'a> Arg<'a> {
/// Wraps the argument without rendering it.
pub fn new<T: std::fmt::Display>(value: &'a T) -> Self {
Self { value }
}
/// Renders the argument for the given precision specifier (`.0` to `.3`), if any. A number
/// given a precision uses the active language's decimal separator.
fn render(&self, spec: Option<&str>) -> String {
let precision = spec.and_then(|spec| spec.strip_prefix('.')).and_then(|digits| digits.parse::<usize>().ok()).filter(|n| *n <= 3);
match precision {
Some(n) => {
let text = format!("{:.*}", n, self.value);
if text.parse::<f64>().is_ok() { current_language().localize_decimal(&text) } else { text }
}
None => self.value.to_string(),
}
}
}
/// Formats the translated `source` with positional arguments. Placeholders may carry a `:.N`
/// precision, as in `format!`; other specifiers are ignored.
pub fn format_positional(source: &str, args: &[Arg<'_>]) -> String {
format_template(source, args, &[], true)
}
/// Formats the translated `source` with named arguments (`name = value`).
pub fn format_named(source: &str, args: &[(&str, Arg<'_>)]) -> String {
format_template(source, &[], args, false)
}
/// Shared implementation behind `format_positional` and `format_named`.
fn format_template(source: &str, positional: &[Arg<'_>], named: &[(&str, Arg<'_>)], positional_mode: bool) -> String {
let template = text(source);
let mut out = String::with_capacity(template.len());
let mut next = 0usize;
let mut chars = template.chars().peekable();
while let Some(ch) = chars.next() {
match ch {
'{' if chars.peek() == Some(&'{') => {
chars.next();
out.push('{');
}
'}' if chars.peek() == Some(&'}') => {
chars.next();
out.push('}');
}
'{' => {
let mut field = String::new();
let mut closed = false;
for ch in chars.by_ref() {
if ch == '}' {
closed = true;
break;
}
field.push(ch);
}
if !closed {
out.push('{');
out.push_str(&field);
break;
}
let (key, spec) = match field.split_once(':') {
Some((key, spec)) => (key, Some(spec)),
None => (field.as_str(), None),
};
let value = if positional_mode {
let value = positional.get(next);
next += 1;
value
} else {
named.iter().find(|(name, _)| *name == key).map(|(_, value)| value)
};
match value {
Some(value) => out.push_str(&value.render(spec)),
None => {
out.push('{');
out.push_str(&field);
out.push('}');
}
}
}
'}' => out.push('}'),
ch => out.push(ch),
}
}
out
}
#[macro_export]
macro_rules! localized_format {
($source:literal) => {
$crate::localization::text($source).to_owned()
};
($source:literal, $($name:ident = $value:expr),+ $(,)?) => {{
$crate::localization::format_named(
$source,
&[$( (stringify!($name), $crate::localization::Arg::new(&$value)) ),+],
)
}};
($source:literal, $($value:expr),+ $(,)?) => {{
$crate::localization::format_positional(
$source,
&[$($crate::localization::Arg::new(&$value)),+],
)
}};
}
#[cfg(test)]
mod tests {
use super::{Arg, Language, enter, error_text, format_named, format_positional, text};
#[test]
fn language_tags_are_stable_and_round_trip() {
for language in Language::ALL {
assert_eq!(Language::parse(language.id()), Some(language));
let encoded = serde_json::to_value(language).unwrap_or_default();
let decoded: Language = serde_json::from_value(encoded).unwrap_or_default();
assert_eq!(decoded, language);
}
assert_eq!(Language::parse(" PT-br "), Some(Language::PortugueseBrazil));
assert_eq!(Language::parse("fr"), None);
}
#[test]
fn language_translations_fall_back_to_the_english_source() {
assert_ne!(Language::PortugueseBrazil.text("Appearance"), "Appearance");
assert_eq!(Language::PortugueseBrazil.text("A source string with no catalog entry"), "A source string with no catalog entry");
assert_eq!(Language::English.text("Appearance"), "Appearance");
}
#[test]
fn language_scope_restores_the_previous_language() {
assert_eq!(text("Appearance"), "Appearance");
{
let _scope = enter(Language::PortugueseBrazil);
assert_ne!(text("Appearance"), "Appearance");
{
let _inner = enter(Language::English);
assert_eq!(text("Appearance"), "Appearance");
}
assert_ne!(text("Appearance"), "Appearance");
}
assert_eq!(text("Appearance"), "Appearance");
}
#[test]
fn portuguese_catalog_covers_every_menu_label() {
for path in include_str!("../../engine/catalog/menus.txt").lines() {
for label in path.split(" > ").map(str::trim).filter(|label| !label.is_empty()) {
assert!(super::pt_br::translate(label).is_some(), "missing pt-BR menu label: {label}");
}
}
}
#[test]
fn engine_errors_are_translated_with_their_values() {
assert_eq!(error_text("select a clip"), "select a clip");
let _scope = enter(Language::PortugueseBrazil);
assert_ne!(error_text("select a clip"), "select a clip");
assert_ne!(error_text("no track"), "no track");
let wrapped = error_text("bad parameters for `track.new`: `name` required");
assert!(wrapped.contains("`track.new`") && wrapped.contains("`name`"), "{wrapped}");
assert!(!wrapped.contains("bad parameters") && !wrapped.contains("required"), "{wrapped}");
let ratio = error_text("stretch ratio 12.500 is outside 0.1..10");
assert!(ratio.contains("12,500"), "{ratio}");
assert_eq!(error_text("some unknown library failure"), "some unknown library failure");
}
#[test]
fn positional_templates_fill_in_order() {
assert_eq!(format_positional("{} of {}", &[Arg::new(&1), Arg::new(&"two")]), "1 of two");
assert_eq!(format_positional("no fields", &[Arg::new(&1)]), "no fields");
}
#[test]
fn named_templates_fill_by_name_in_any_order() {
assert_eq!(format_named("{b}-{a}-{b}", &[("a", Arg::new(&1)), ("b", Arg::new(&2))]), "2-1-2");
}
#[test]
fn precision_specifiers_are_honoured() {
let value = 3.14259_f64;
for (template, expected) in [("{:.0}", "3"), ("{:.1}", "3.1"), ("{:.2}", "3.14"), ("{:.3}", "3.143"), ("{}", "3.14259")] {
assert_eq!(format_positional(template, &[Arg::new(&value)]), expected, "{template}");
}
}
#[test]
fn braces_can_be_escaped() {
assert_eq!(format_positional("{{{}}}", &[Arg::new(&5)]), "{5}");
}
#[test]
fn missing_unknown_and_unclosed_fields_are_kept_verbatim() {
assert_eq!(format_positional("{} {}", &[Arg::new(&1)]), "1 {}");
assert_eq!(format_named("{nope}", &[("a", Arg::new(&1))]), "{nope}");
assert_eq!(format_positional("open {", &[]), "open {");
assert_eq!(format_positional("tail {abc", &[]), "tail {abc");
}
#[test]
fn portuguese_numbers_use_a_decimal_comma_only_with_a_precision() {
let _scope = enter(Language::PortugueseBrazil);
assert_eq!(format_positional("{:.1} dB", &[Arg::new(&-6.04_f64)]), "-6,0 dB");
assert_eq!(format_positional("{}", &[Arg::new(&"v1.2")]), "v1.2");
let _english = enter(Language::English);
assert_eq!(format_positional("{:.1}", &[Arg::new(&2.5_f64)]), "2.5");
}
/// Parses a Rust string literal at the start of `s`; returns its value and the rest.
fn literal(s: &str) -> Option<(String, &str)> {
let mut chars = s.strip_prefix('"')?.char_indices();
let mut out = String::new();
while let Some((i, c)) = chars.next() {
match c {
'"' => return Some((out, &s[i + 2..])),
'\\' => match chars.next()?.1 {
'n' => out.push('\n'),
other => out.push(other),
},
c => out.push(c),
}
}
None
}
/// Every `"source" => "translation"` pair of the catalog, read from its source file.
fn catalog_entries() -> Vec<(String, String)> {
let text = include_str!("../locales/pt-BR/mod.rs");
let mut lines = text.lines().map(str::trim);
let mut entries = Vec::new();
while let Some(line) = lines.next() {
let Some((key, rest)) = literal(line) else { continue };
let Some(rest) = rest.trim_start().strip_prefix("=>") else { continue };
let rest = rest.trim();
let value =
if rest.starts_with('{') { lines.next().and_then(|next| literal(next).map(|(v, _)| v)) } else { literal(rest).map(|(v, _)| v) };
if let Some(value) = value {
entries.push((key, value));
}
}
entries
}
fn placeholders(template: &str) -> Vec<String> {
let mut found = Vec::new();
let mut chars = template.chars().peekable();
while let Some(c) = chars.next() {
if c == '{' && chars.peek() == Some(&'{') {
chars.next();
} else if c == '{' {
let field: String = chars.by_ref().take_while(|c| *c != '}').collect();
found.push(field);
}
}
found.sort();
found
}
#[test]
fn catalog_entries_are_parsed_and_unique() {
let entries = catalog_entries();
assert!(entries.len() > 1000, "parsed only {} catalog entries", entries.len());
let mut keys: Vec<&str> = entries.iter().map(|(key, _)| key.as_str()).collect();
keys.sort_unstable();
let before = keys.len();
keys.dedup();
assert_eq!(before, keys.len(), "duplicate catalog keys");
}
#[test]
fn catalog_translations_keep_the_english_placeholders() {
for (source, translation) in catalog_entries() {
assert_eq!(placeholders(&source), placeholders(&translation), "placeholders differ for {source:?}");
assert_eq!(super::pt_br::translate(&source), Some(translation.as_str()), "lookup differs for {source:?}");
}
}
#[test]
fn every_localized_source_string_has_a_catalog_entry() {
fn visit(dir: &std::path::Path, missing: &mut Vec<String>) {
let Ok(read) = std::fs::read_dir(dir) else { return };
for entry in read.flatten() {
let path = entry.path();
if path.is_dir() {
visit(&path, missing);
} else if path.extension().is_some_and(|e| e == "rs") && !path.ends_with("localization.rs") {
let Ok(text) = std::fs::read_to_string(&path) else { continue };
for marker in ["localization::text(\"", "localized_format!(\""] {
for (at, _) in text.match_indices(marker) {
let start = at + marker.len() - 1;
if let Some((source, _)) = literal(&text[start..])
&& super::pt_br::translate(&source).is_none()
{
missing.push(format!("{}: {source:?}", path.display()));
}
}
}
}
}
}
let mut missing = Vec::new();
visit(&std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src"), &mut missing);
assert!(missing.is_empty(), "strings without a pt-BR entry:\n{}", missing.join("\n"));
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.