Skip to main content

rustango_cms/
translation.rs

1//! Per-field, per-locale translation overrides.
2//!
3//! Design rationale lives in `docs/i18n-decision.md`. The
4//! TL;DR: the canonical `cms_page` row holds the default-locale
5//! content; `cms_translation` overrides individual fields per locale.
6//! This table is the sole supported localization path — the
7//! `cms_page.locale_variant_of` escape hatch was retired.
8//!
9//! Storage rationale: a wide JSON blob per page works for
10//! document-shaped DBs but is awkward in PG/MySQL where
11//! ordinary SELECT + indexes want columns. The narrow tall table is
12//! easier to query, easier to migrate, and keeps the canonical
13//! `cms_page` row free of locale concerns.
14
15use chrono::{DateTime, Utc};
16use rustango::sql::Auto;
17use rustango::Model;
18use serde::{Deserialize, Serialize};
19
20/// One row per `(page_id, locale_id, field_path)`. An empty
21/// `value` is treated as "no override" and the canonical content
22/// shows through.
23#[derive(Model, Debug, Clone, Serialize, Deserialize)]
24#[rustango(
25    table = "cms_translation",
26    app = "cms",
27    admin(
28        list_display = "page_id, locale_id, field_path, value, updated_at",
29        ordering = "page_id",
30        list_filter = "locale_id, field_path",
31    )
32)]
33pub struct Translation {
34    #[rustango(primary_key)]
35    pub id: Auto<i64>,
36
37    #[rustango(fk = "cms_page", on = "id", index)]
38    pub page_id: i64,
39
40    #[rustango(fk = "cms_locale", on = "id", index)]
41    pub locale_id: i64,
42
43    /// Field name on `cms_page`. Scalar columns (`title`, `seo_title`,
44    /// `seo_description`); a whole-body StreamField blob (the bare stream
45    /// field name, e.g. `body`); or a dotted **block-UUID path** into a
46    /// StreamField for per-leaf translation, incl. nested blocks —
47    /// `<field>.<uuid>.<name>` / `<field>.<uuid>.<sub>.<uuid>.<name>`
48    /// (see [`crate::block::translate`]). 255 fits ~2 levels of UUIDs.
49    #[rustango(max_length = 255, index)]
50    pub field_path: String,
51
52    /// Localized value. Empty string = "no override".
53    pub value: String,
54
55    #[rustango(auto_now)]
56    pub updated_at: Auto<DateTime<Utc>>,
57}
58
59/// Fetch every translation for `(page_id, locale_id)` as a map
60/// keyed on `field_path`. Single SELECT, materialized once per
61/// rendered request.
62///
63/// # Errors
64/// Driver / query failures.
65pub async fn fetch_for(
66    pool: &rustango::sql::Pool,
67    page_id: i64,
68    locale_id: i64,
69) -> Result<std::collections::HashMap<String, String>, rustango::sql::ExecError> {
70    use rustango::core::Column as _;
71    use rustango::sql::FetcherPool as _;
72
73    let rows: Vec<Translation> = Translation::objects()
74        .where_(Translation::page_id.eq(page_id))
75        .where_(Translation::locale_id.eq(locale_id))
76        .fetch(pool)
77        .await?;
78    Ok(rows
79        .into_iter()
80        .filter(|t| !t.value.is_empty())
81        .map(|t| (t.field_path, t.value))
82        .collect())
83}
84
85/// Fetch translations for every page in `page_ids` under one
86/// `locale_id`, materialized as `{ page_id -> { field_path -> value } }`.
87///
88/// Single `WHERE locale_id = $1 AND page_id IN (...)` SELECT — used by
89/// the renderer to populate `translations_by_page` so child / ancestor
90/// templates can translate the fields they display (titles in card
91/// grids, breadcrumbs, etc.) without N round-trips.
92///
93/// Returns an empty map when `page_ids` is empty. Empty `value`s are
94/// dropped — the canonical content shows through.
95///
96/// # Errors
97/// Driver / query failures.
98pub async fn fetch_for_pages(
99    pool: &rustango::sql::Pool,
100    page_ids: &[i64],
101    locale_id: i64,
102) -> Result<
103    std::collections::HashMap<i64, std::collections::HashMap<String, String>>,
104    rustango::sql::ExecError,
105> {
106    use rustango::core::Column as _;
107    use rustango::sql::FetcherPool as _;
108
109    if page_ids.is_empty() {
110        return Ok(std::collections::HashMap::new());
111    }
112    let rows: Vec<Translation> = Translation::objects()
113        .where_(Translation::locale_id.eq(locale_id))
114        .where_(Translation::page_id.is_in(page_ids.iter().copied()))
115        .fetch(pool)
116        .await?;
117    let mut out: std::collections::HashMap<i64, std::collections::HashMap<String, String>> =
118        std::collections::HashMap::new();
119    for row in rows {
120        if row.value.is_empty() {
121            continue;
122        }
123        out.entry(row.page_id)
124            .or_default()
125            .insert(row.field_path, row.value);
126    }
127    Ok(out)
128}
129
130/// Overlay seeded per-page scalar translations onto a JSON context value
131/// so templates render localized content with **no** `t`-filter calls —
132/// the engine localizes `page`, `extension`, `children`, and any
133/// handler-supplied card/list objects uniformly (the same "it just
134/// works" contract StreamField bodies already get via the stream
135/// prerender).
136///
137/// Recurses through objects/arrays. For any object that identifies a
138/// page (a `page_id` or `id` field whose value is a key in `by_page`),
139/// each **scalar** field translation (`field_path` has no `.`, so
140/// StreamField body leaves — already localized upstream — are skipped)
141/// **replaces** the object's existing same-named field. Fields the
142/// object does not already expose are never injected, so an unrelated
143/// object that merely shares an id value is left untouched.
144///
145/// No-op when `by_page` is empty (the default locale), so canonical
146/// content shows through unchanged.
147pub fn overlay_translations(
148    value: &mut serde_json::Value,
149    by_page: &std::collections::HashMap<i64, std::collections::HashMap<String, String>>,
150) {
151    match value {
152        serde_json::Value::Object(map) => {
153            let pid = map
154                .get("page_id")
155                .or_else(|| map.get("id"))
156                .and_then(serde_json::Value::as_i64);
157            if let Some(tr) = pid.and_then(|p| by_page.get(&p)) {
158                for (field_path, translated) in tr {
159                    if !field_path.contains('.')
160                        && !translated.is_empty()
161                        && map.contains_key(field_path)
162                    {
163                        map.insert(
164                            field_path.clone(),
165                            serde_json::Value::String(translated.clone()),
166                        );
167                    }
168                }
169            }
170            for v in map.values_mut() {
171                overlay_translations(v, by_page);
172            }
173        }
174        serde_json::Value::Array(arr) => {
175            for v in arr.iter_mut() {
176                overlay_translations(v, by_page);
177            }
178        }
179        _ => {}
180    }
181}
182
183/// Validate a translation `field_path`: ≤255 chars, ASCII alphanumeric
184/// plus `_`, `.`, and `-`. The `.` allows dotted block-UUID paths into
185/// StreamFields (`<field>.<uuid>.<name>`); the `-` is required because
186/// block UUIDs are lowercase hex with hyphens. Returns the trimmed path
187/// on success. Pure — unit-tested + reused by the page translate
188/// handler's "add new key" guard.
189///
190/// # Errors
191/// A human-readable message when the path is empty, too long, or has
192/// disallowed characters.
193pub fn validate_field_path(raw: &str) -> Result<String, String> {
194    let p = raw.trim();
195    if p.is_empty() {
196        return Err("Field name is required.".to_owned());
197    }
198    if p.chars().count() > 255 {
199        return Err("Field name is too long (max 255 characters).".to_owned());
200    }
201    if !p
202        .chars()
203        .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '.' || c == '-')
204    {
205        return Err("Field name may only contain letters, digits, '_', '.' and '-'.".to_owned());
206    }
207    Ok(p.to_owned())
208}
209
210/// Resolve a locale, taking precedence:
211///
212/// 1. `explicit_code` (an active `cms_locale` code).
213/// 2. The tenant's default locale (`cms_locale.is_default = true`).
214///
215/// `Accept-Language` negotiation happens upstream, in
216/// `locale_mode::resolve_request_locale`.
217///
218/// Returns the matched `cms_locale.id`, or `None` if no locale was
219/// requested AND no default exists (the canonical row stays as-is).
220pub async fn resolve_locale(
221    pool: &rustango::sql::Pool,
222    explicit_code: Option<&str>,
223) -> Result<Option<crate::locale::Locale>, rustango::sql::ExecError> {
224    use rustango::core::Column as _;
225    use rustango::sql::FetcherPool as _;
226    if let Some(code) = explicit_code {
227        let mut hits: Vec<crate::locale::Locale> = crate::locale::Locale::objects()
228            .where_(crate::locale::Locale::code.eq(code.to_owned()))
229            .where_(crate::locale::Locale::active.eq(true))
230            .fetch(pool)
231            .await?;
232        if let Some(l) = hits.pop() {
233            return Ok(Some(l));
234        }
235        // Unknown code → silently fall through to default. The
236        // alternative (404) would surprise users following a stale
237        // link.
238    }
239    let mut defaults: Vec<crate::locale::Locale> = crate::locale::Locale::objects()
240        .where_(crate::locale::Locale::is_default.eq(true))
241        .fetch(pool)
242        .await?;
243    Ok(defaults.pop())
244}
245
246// ---------- Tera filter ----------
247
248/// Tera filter `t(field=..., translations=...)` — substitute the
249/// localized value for `field` from the supplied translations map,
250/// falling back to the original input on miss / empty.
251///
252/// Usage:
253/// ```tera
254/// <h1>{{ page.title | t(field="title", translations=translations) }}</h1>
255/// ```
256pub fn register_tera_filter(tera: &mut tera::Tera) {
257    tera.register_filter("t", t_filter);
258}
259
260fn t_filter(
261    value: &tera::Value,
262    args: &std::collections::HashMap<String, tera::Value>,
263) -> tera::Result<tera::Value> {
264    let field = args
265        .get("field")
266        .and_then(tera::Value::as_str)
267        .ok_or_else(|| tera::Error::msg("t filter: `field` (string) is required"))?;
268
269    // Primary form: `translations` is a flat field→value map for the
270    // current page. Used everywhere the rendered page itself owns the
271    // text (titles, body, lead, etc.).
272    if let Some(map) = args.get("translations").and_then(tera::Value::as_object) {
273        if let Some(v) = map.get(field).and_then(tera::Value::as_str) {
274            if !v.is_empty() {
275                return Ok(tera::Value::String(v.to_owned()));
276            }
277        }
278    }
279
280    // Loop form: inside `{% for c in children %}` etc., templates pass
281    // `by_page=translations_by_page, page_id=c.id` so each iteration
282    // translates against the child's own row.
283    if let (Some(by_page), Some(page_id)) = (args.get("by_page"), args.get("page_id")) {
284        let key = match page_id {
285            tera::Value::Number(n) => n.to_string(),
286            tera::Value::String(s) => s.clone(),
287            _ => String::new(),
288        };
289        if let Some(per_page) = by_page.as_object().and_then(|m| m.get(&key)) {
290            if let Some(v) = per_page
291                .as_object()
292                .and_then(|m| m.get(field))
293                .and_then(tera::Value::as_str)
294            {
295                if !v.is_empty() {
296                    return Ok(tera::Value::String(v.to_owned()));
297                }
298            }
299        }
300    }
301
302    Ok(value.clone())
303}
304
305#[cfg(test)]
306mod tests {
307    use super::validate_field_path;
308
309    #[test]
310    fn validate_field_path_accepts_scalar_dotted_and_block_paths() {
311        assert_eq!(validate_field_path("title").unwrap(), "title");
312        assert_eq!(validate_field_path("  body ").unwrap(), "body");
313        // dotted block-UUID path into a StreamField (incl. nested)
314        let p = "body.550e8400-e29b-41d4-a716-446655440000.title";
315        assert_eq!(validate_field_path(p).unwrap(), p);
316        let nested = "body.550e8400-e29b-41d4-a716-446655440000.params.\
317                      11111111-2222-3333-4444-555555555555.description";
318        assert_eq!(validate_field_path(nested).unwrap(), nested);
319    }
320
321    #[test]
322    fn validate_field_path_rejects_garbage_and_overlong() {
323        assert!(validate_field_path("").is_err());
324        assert!(validate_field_path("   ").is_err());
325        assert!(validate_field_path("has space").is_err());
326        assert!(validate_field_path("semi;colon").is_err());
327        assert!(validate_field_path(&"x".repeat(256)).is_err());
328        assert!(validate_field_path(&"a".repeat(255)).is_ok());
329    }
330}