Skip to main content

day_localization_ui/
lib.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! day-localization-ui: the piece-facing localization layer over the [`day_localization`] engine (DESIGN.md §12).
5//!
6//! The engine (bundles, the current-locale signal, `format_in`, and the built-in core catalog of
7//! standard UI strings) now lives in `day-localization`, low enough that the central crates localize their
8//! own strings. This crate re-exports that engine and adds the reactive `tr()` **text source**:
9//! `label(tr("greeting").arg("name", name))`, whose value re-reads the locale signal plus any signal
10//! args, so a locale switch updates every visible string fine-grained, followed by one relayout.
11
12// Re-export the engine so the app-facing API (`install_locales`, `set_locale`, …) is unchanged.
13pub use day_localization::{
14    Catalog, DateFields, FArg, IntoFArg, IntoNumberFArg, SigM, ValM, add_launch_locales, compare,
15    compare_in, format_catalog, format_date, format_date_in, format_decimal, format_decimal_in,
16    format_in, format_percent, format_percent_in, key, locale, matches_search, matches_search_in,
17    register_catalog, set_launch_locale, set_launch_locales, set_locale, sort_localized,
18    strip_isolates, t,
19};
20
21/// Register the app's locales (see [`day_localization::install`]) and fix the layout direction from the
22/// locale that actually resolved (docs/localization): an RTL locale (Arabic, Hebrew, …) mirrors
23/// every horizontal placement and flips the native toolkit's direction. Direction is resolved
24/// once, before the first layout; runtime `set_locale` switches strings but not direction.
25pub fn install(default: &str, locales: &[(&str, &str)]) {
26    day_localization::install(default, locales);
27    day_core::set_layout_direction(day_core::direction_of_locale(
28        &day_localization::locale().get_untracked(),
29    ));
30}
31
32/// A localized text source: `label(tr("greeting").arg("name", name))` (§12.2).
33#[derive(Clone)]
34pub struct LocalizedText {
35    key: String,
36    catalog: Option<&'static Catalog>,
37    args: Vec<(String, FArg)>,
38}
39
40pub fn tr(key: &str) -> LocalizedText {
41    LocalizedText {
42        key: key.to_owned(),
43        catalog: None,
44        args: Vec::new(),
45    }
46}
47
48/// Bind a key to a private crate/file catalog. Prefer generated typed accessors.
49pub fn tr_in(catalog: &'static Catalog, key: &str) -> LocalizedText {
50    register_catalog(catalog);
51    LocalizedText {
52        key: key.to_owned(),
53        catalog: Some(catalog),
54        args: Vec::new(),
55    }
56}
57
58/// Day's own strings, named the way an app's are: `res::str::day_cancel()`,
59/// `res::str::day_about_app(name)`, one typed function per message in the core catalog
60/// (`day-localization/catalog/en.ftl`), generated from it at build time (docs/localization.md).
61///
62/// An app reaches these through its own `res::str`, which re-exports them beside its messages, so
63/// `res::str::day_about_website()` works there too, and a message the app defines under the same
64/// name overrides the core one. Pieces with no `res` of their own call `day_localization_ui::res::str`.
65pub mod res {
66    /// The core catalog's messages as typed [`LocalizedText`](crate::LocalizedText) constructors.
67    pub mod str {
68        use crate::{LocalizedText, tr};
69        day_localization::__core_strings!();
70    }
71}
72
73/// Include the private localization modules written by `day_build::generate_locales()`.
74/// Usable by reusable pieces without depending on the `day` umbrella crate.
75#[macro_export]
76macro_rules! locales {
77    () => {
78        pub mod res {
79            include!(concat!(env!("OUT_DIR"), "/day_locales.rs"));
80        }
81    };
82}
83
84impl LocalizedText {
85    #[must_use]
86    pub fn arg<M>(mut self, name: &str, value: impl IntoFArg<M>) -> Self {
87        self.args.push((name.to_owned(), value.into_farg()));
88        self
89    }
90
91    /// Tracked format: reads the locale signal + any signal args.
92    #[must_use]
93    pub fn format(&self) -> String {
94        match self.catalog {
95            Some(catalog) => format_catalog(catalog, &locale().get(), &self.key, &self.args),
96            None => format_in(&locale().get(), &self.key, &self.args),
97        }
98    }
99}
100
101/// A formatted snapshot in the current locale, for the places that hold a `String`. Lets a
102/// closure returning a `LocalizedText` be an `IntoText` too (`label(move || res::str::n(count.get()))`),
103/// since the closure form converts through `Into<String>`.
104impl From<LocalizedText> for String {
105    fn from(t: LocalizedText) -> String {
106        t.format()
107    }
108}