Derive i18n support

Cargo.toml

@@ -14,7 +14,6 @@ members = [
     "askama_hyper",
     "testing",
 ]
-resolver = "2"
 
 default-members = [
     "askama",
@@ -23,3 +22,5 @@ default-members = [
     "askama_parser",
     "testing",
 ]
+
+resolver = "2"

askama/Cargo.toml

@@ -20,6 +20,7 @@ maintenance = { status = "actively-developed" }
 default = ["config", "humansize", "num-traits", "urlencode"]
 config = ["askama_derive/config"]
 humansize = ["askama_derive/humansize", "dep_humansize"]
+i18n = ["askama_derive/i18n", "fluent-templates", "parking_lot"]
 markdown = ["askama_derive/markdown", "comrak"]
 num-traits = ["askama_derive/num-traits", "dep_num_traits"]
 serde-json = ["askama_derive/serde-json", "askama_escape/json", "serde", "serde_json"]
@@ -44,6 +45,8 @@ askama_escape = { version = "0.10.3", path = "../askama_escape" }
 comrak = { version = "0.20", optional = true, default-features = false }
 dep_humansize = { package = "humansize", version = "2", optional = true }
 dep_num_traits = { package = "num-traits", version = "0.2.6", optional = true }
+fluent-templates = { version = "0.8.0", optional = true }
+parking_lot = { version = "0.12.1", optional = true }
 percent-encoding = { version = "2.1.0", optional = true }
 serde = { version = "1.0", optional = true, features = ["derive"] }
 serde_json = { version = "1.0", optional = true }

askama/src/i18n.rs

@@ -0,0 +1,129 @@
+//! Module for compile time checked localization
+//!
+//! # Example:
+//!
+//! [Fluent Translation List](https://projectfluent.org/) resource file `i18n/es-MX/basic.ftl`:
+//!
+//! ```ftl
+//! greeting = ¡Hola, { $name }!
+//! ```
+//!
+//! Askama HTML template `templates/example.html`:
+//!
+//! ```html
+//! <h1>{{ localize("greeting", name: name) }}</h1>
+//! ```
+//!
+//! Rust usage:
+//! ```ignore
+//! use askama::i18n::{langid, Locale};
+//! use askama::Template;
+//!
+//! askama::i18n::load!(LOCALES);
+//!
+//! #[derive(Template)]
+//! #[template(path = "example.html")]
+//! struct ExampleTemplate<'a> {
+//!     #[locale]
+//!     loc: Locale<'a>,
+//!     name: &'a str,
+//! }
+//!
+//! let template = ExampleTemplate {
+//!     loc: Locale::new(langid!("es-MX"), &LOCALES),
+//!     name: "Hilda",
+//! };
+//!
+//! // "<h1>¡Hola, Hilda!</h1>"
+//! template.render().unwrap();
+//! ```
+
+use std::collections::HashMap;
+use std::iter::FromIterator;
+
+// Re-export conventiently as `askama::i18n::load!()`.
+// Proc-macro crates can only export macros from their root namespace.
+/// Load locales at compile time. See example above for usage.
+pub use askama_derive::i18n_load as load;
+
+pub use fluent_templates::{self, fluent_bundle::FluentValue, fs::langid, LanguageIdentifier};
+use fluent_templates::{Loader, StaticLoader};
+use parking_lot::const_mutex;
+
+pub struct Locale<'a> {
+    loader: &'a StaticLoader,
+    language: LanguageIdentifier,
+}
+
+impl Locale<'_> {
+    pub fn new(language: LanguageIdentifier, loader: &'static StaticLoader) -> Self {
+        Self { loader, language }
+    }
+
+    pub fn translate<'a>(
+        &self,
+        msg_id: &str,
+        args: impl IntoIterator<Item = (&'a str, FluentValue<'a>)>,
+    ) -> Option<String> {
+        let args = HashMap::<&str, FluentValue<'_>>::from_iter(args);
+        let args = match args.is_empty() {
+            true => None,
+            false => Some(&args),
+        };
+        self.loader.lookup_complete(&self.language, msg_id, args)
+    }
+}
+
+/// Similar to OnceCell, but it has an additional take() function, which can only be used once,
+/// and only if the instance was never dereferenced.
+///
+/// The struct is only meant to be used by the [`i18n_load!()`] macro.
+/// Concurrent access will deliberately panic.
+///
+/// Rationale: StaticLoader cannot be cloned.
+#[doc(hidden)]
+pub struct Unlazy<T>(parking_lot::Mutex<UnlazyEnum<T>>);
+
+enum UnlazyEnum<T> {
+    Generator(Option<fn() -> T>),
+    Value(Box<T>),
+}
+
+impl<T> Unlazy<T> {
+    pub const fn new(f: fn() -> T) -> Self {
+        Self(const_mutex(UnlazyEnum::Generator(Some(f))))
+    }
+
+    pub fn take(&self) -> T {
+        let f = match &mut *self.0.try_lock().unwrap() {
+            UnlazyEnum::Generator(f) => f.take(),
+            _ => None,
+        };
+        f.unwrap()()
+    }
+}
+
+impl<T> std::ops::Deref for Unlazy<T>
+where
+    Self: 'static,
+{
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        let data = &mut *self.0.try_lock().unwrap();
+        let value: &T = match data {
+            UnlazyEnum::Generator(f) => {
+                *data = UnlazyEnum::Value(Box::new(f.take().unwrap()()));
+                match data {
+                    UnlazyEnum::Value(value) => value,
+                    _ => unreachable!(),
+                }
+            }
+            UnlazyEnum::Value(value) => value,
+        };
+
+        // SAFETY: This transmutation is safe because once a value is assigned,
+        //         it won't be unassigned again, and Self has static lifetime.
+        unsafe { std::mem::transmute(value) }
+    }
+}

askama/src/lib.rs

@@ -59,13 +59,15 @@
 //!   in the configuration file. The default syntax , "default",  is the one
 //!   provided by Askama.
 
-#![forbid(unsafe_code)]
+#![cfg_attr(not(feature = "i18n"), forbid(unsafe_code))]
 #![deny(elided_lifetimes_in_paths)]
 #![deny(unreachable_pub)]
 
 mod error;
 pub mod filters;
 pub mod helpers;
+#[cfg(feature = "i18n")]
+pub mod i18n;
 
 use std::fmt;
 

askama_derive/Cargo.toml

@@ -16,11 +16,12 @@ proc-macro = true
 [features]
 config = ["serde", "basic-toml"]
 humansize = []
+i18n = ["fluent-syntax", "fluent-templates", "serde", "basic-toml", "parser/i18n"]
 markdown = []
-urlencode = []
+num-traits = []
 serde-json = []
 serde-yaml = []
-num-traits = []
+urlencode = []
 with-actix-web = []
 with-axum = []
 with-gotham = []
@@ -31,6 +32,8 @@ with-tide = []
 with-warp = []
 
 [dependencies]
+fluent-syntax = { version = "0.11.0", optional = true, default-features = false }
+fluent-templates = { version = "0.8.0", optional = true, default-features = false }
 parser = { package = "askama_parser", version = "0.2", path = "../askama_parser" }
 mime = "0.3"
 mime_guess = "2"

askama_derive/src/generator.rs

@@ -1154,10 +1154,43 @@ impl<'a> Generator<'a> {
             Expr::RustMacro(ref path, args) => self.visit_rust_macro(buf, path, args),
             Expr::Try(ref expr) => self.visit_try(buf, expr.as_ref())?,
             Expr::Tuple(ref exprs) => self.visit_tuple(buf, exprs)?,
+            #[cfg(feature = "i18n")]
+            Expr::Localize(ref msg_id, ref args) => self.visit_localize(buf, msg_id, args)?,
             Expr::NamedArgument(_, ref expr) => self.visit_named_argument(buf, expr)?,
         })
     }
 
+    #[cfg(feature = "i18n")]
+    fn visit_localize(
+        &mut self,
+        buf: &mut Buffer,
+        msg_id: &Expr<'_>,
+        args: &[(&str, Expr<'_>)],
+    ) -> Result<DisplayWrap, CompileError> {
+        let localizer =
+            self.input.localizer.as_deref().ok_or(
+                "You need to annotate a field with #[locale] to use the localize() function.",
+            )?;
+
+        buf.write(&format!(
+            "self.{}.translate(",
+            normalize_identifier(localizer)
+        ));
+        self.visit_expr(buf, msg_id)?;
+        buf.writeln(", [")?;
+        buf.indent();
+        for (k, v) in args {
+            buf.write(&format!("({:?}, ::askama::i18n::FluentValue::from(", k));
+            self.visit_expr(buf, v)?;
+            buf.writeln(")),")?;
+        }
+        buf.dedent()?;
+        // Safe to unwrap, as `msg_id` is checked at compile time.
+        buf.write("]).unwrap()");
+
+        Ok(DisplayWrap::Unwrapped)
+    }
+
     fn visit_try(
         &mut self,
         buf: &mut Buffer,
@@ -1984,6 +2017,10 @@ pub(crate) fn is_cacheable(expr: &Expr<'_>) -> bool {
         Expr::Group(arg) => is_cacheable(arg),
         Expr::Tuple(args) => args.iter().all(is_cacheable),
         Expr::NamedArgument(_, expr) => is_cacheable(expr),
+        #[cfg(feature = "i18n")]
+        Expr::Localize(msg_id, args) => {
+            is_cacheable(msg_id) && args.iter().all(|(_, arg)| is_cacheable(arg))
+        }
         // We have too little information to tell if the expression is pure:
         Expr::Call(_, _) => false,
         Expr::RustMacro(_, _) => false,