Skip to main content

rustango_cms/block/
translate.rs

1//! Recursive per-leaf translation walker for StreamField content.
2//!
3//! StreamField bodies are `[{type, id, value}]` arrays
4//! where `value` is a field-name dict (or a bare scalar for a
5//! single-field block). Blocks can nest other streams (`Stream` /
6//! `Repeat` fields), to any depth. This module walks that tree two ways,
7//! both schema-driven via the block registry (so only declared
8//! translatable-text leaves are ever touched):
9//!
10//! * [`collect_translatable_leaves`] — enumerate every translatable text
11//!   leaf with a stable dotted path, for the admin translation editor.
12//! * [`apply_translatable_overrides`] — produce a localized clone of the
13//!   stream with each leaf replaced by its per-locale override.
14//!
15//! ## Path scheme
16//! Leaves are keyed by **block UUID** (client-minted, never re-minted),
17//! so paths survive block reordering:
18//!
19//! * top-level leaf:        `<streamfield>.<uuid>.<fieldname>`
20//! * nested stream/repeat:  `<streamfield>.<uuid>.<subfield>.<subuuid>.<fieldname>`
21//!
22//! Only [`WidgetKind::is_translatable_text`] leaves get paths; structural
23//! fields (choosers, numbers, choices, urls) and `Computed` fields are
24//! skipped. Unregistered (drift) blocks are skipped entirely — never
25//! translated, and passed through unchanged on apply.
26
27use std::collections::HashMap;
28
29use serde_json::Value;
30
31use super::BlockField;
32use crate::widget::WidgetKind;
33
34/// One translatable text leaf discovered in a StreamField tree.
35#[derive(Debug, Clone)]
36pub struct TranslatableLeaf {
37    /// Full dotted path (incl. the streamfield prefix) — the
38    /// `cms_translation.field_path` key for this leaf.
39    pub path: String,
40    /// The leaf's widget kind (`Text` / `Textarea` / `Markdown` /
41    /// `RichText`) — drives the editor input type.
42    pub widget_kind: WidgetKind,
43    /// Canonical (default-locale) text; empty when absent/non-string.
44    pub canonical_text: String,
45    /// Wire type of the owning block (e.g. `"callout"`).
46    pub block_type: String,
47    /// Human label of the owning block (`verbose_name`), for UI grouping.
48    pub block_label: String,
49    /// The `BlockField` label, for the editor row.
50    pub field_label: String,
51    /// Block instance UUID that owns this leaf (for grouping rows).
52    pub block_id: String,
53    /// Nesting depth: 0 for a leaf in a top-level block, +1 per nested
54    /// stream/repeat container — used to indent the editor UI.
55    pub depth: usize,
56}
57
58/// Collect every translatable text leaf in `canonical_stream` (an
59/// already-parsed block array), in document order. `stream_field_name`
60/// is the owning StreamField widget name (the path prefix).
61#[must_use]
62pub fn collect_translatable_leaves(
63    stream_field_name: &str,
64    canonical_stream: &Value,
65) -> Vec<TranslatableLeaf> {
66    collect_translatable_leaves_with(stream_field_name, canonical_stream, None)
67}
68
69/// [`collect_translatable_leaves`] with a page-builder dyn-block overlay:
70/// UI-defined group/repeater/component blocks resolve through
71/// `dyn_set` before the inventory registry, so their text leaves are
72/// enumerated exactly like code-registered blocks.
73#[must_use]
74pub fn collect_translatable_leaves_with(
75    stream_field_name: &str,
76    canonical_stream: &Value,
77    dyn_set: Option<&crate::page_builder::DynBlockSet>,
78) -> Vec<TranslatableLeaf> {
79    let mut out = Vec::new();
80    if let Value::Array(arr) = canonical_stream {
81        collect_blocks(arr, stream_field_name, 0, dyn_set, &mut out);
82    }
83    out
84}
85
86fn collect_blocks(
87    arr: &[Value],
88    prefix: &str,
89    depth: usize,
90    dyn_set: Option<&crate::page_builder::DynBlockSet>,
91    out: &mut Vec<TranslatableLeaf>,
92) {
93    for env in arr {
94        let (Some(btype), Some(bid)) = (
95            env.get("type").and_then(Value::as_str),
96            env.get("id").and_then(Value::as_str),
97        ) else {
98            continue; // missing type/id — no stable key
99        };
100        let Some(block) = crate::page_builder::resolve_block(dyn_set, btype) else {
101            continue; // drift / unregistered — skip (renderer shows a banner)
102        };
103        let fields = block.fields();
104        let value_obj = normalize_value(env.get("value"), &fields);
105        let block_prefix = format!("{prefix}.{bid}");
106        for field in &fields {
107            match field {
108                BlockField::Widget {
109                    name,
110                    label,
111                    widget,
112                    ..
113                } if widget.is_translatable_text() => {
114                    out.push(TranslatableLeaf {
115                        path: format!("{block_prefix}.{name}"),
116                        widget_kind: widget.clone(),
117                        canonical_text: value_obj
118                            .get(name)
119                            .and_then(Value::as_str)
120                            .unwrap_or("")
121                            .to_owned(),
122                        block_type: btype.to_owned(),
123                        block_label: block.verbose_name().to_owned(),
124                        field_label: label.clone(),
125                        block_id: bid.to_owned(),
126                        depth,
127                    });
128                }
129                BlockField::Stream { name, .. } | BlockField::Repeat { name, .. } => {
130                    if let Some(Value::Array(sub)) = value_obj.get(name) {
131                        collect_blocks(
132                            sub,
133                            &format!("{block_prefix}.{name}"),
134                            depth + 1,
135                            dyn_set,
136                            out,
137                        );
138                    }
139                }
140                _ => {}
141            }
142        }
143    }
144}
145
146/// Return a localized clone of `canonical_stream`: every translatable
147/// text leaf whose dotted path has a non-empty entry in `translations`
148/// is replaced with that override; missing/empty overrides leave the
149/// canonical text intact (per-leaf fallback). Structural fields, block
150/// types, ids, and ordering are untouched. Unregistered blocks pass
151/// through unchanged.
152#[must_use]
153pub fn apply_translatable_overrides(
154    stream_field_name: &str,
155    canonical_stream: &Value,
156    translations: &HashMap<String, String>,
157) -> Value {
158    apply_translatable_overrides_with(stream_field_name, canonical_stream, translations, None)
159}
160
161/// [`apply_translatable_overrides`] with a page-builder dyn-block overlay
162/// so UI-defined blocks localize like code-registered ones.
163#[must_use]
164pub fn apply_translatable_overrides_with(
165    stream_field_name: &str,
166    canonical_stream: &Value,
167    translations: &HashMap<String, String>,
168    dyn_set: Option<&crate::page_builder::DynBlockSet>,
169) -> Value {
170    let mut cloned = canonical_stream.clone();
171    if let Value::Array(arr) = &mut cloned {
172        apply_blocks(arr, stream_field_name, translations, dyn_set);
173    }
174    cloned
175}
176
177fn apply_blocks(
178    arr: &mut [Value],
179    prefix: &str,
180    translations: &HashMap<String, String>,
181    dyn_set: Option<&crate::page_builder::DynBlockSet>,
182) {
183    for env in arr.iter_mut() {
184        let btype = env.get("type").and_then(Value::as_str).map(str::to_owned);
185        let bid = env.get("id").and_then(Value::as_str).map(str::to_owned);
186        let (Some(btype), Some(bid)) = (btype, bid) else {
187            continue;
188        };
189        let Some(block) = crate::page_builder::resolve_block(dyn_set, &btype) else {
190            continue; // drift — pass through unchanged
191        };
192        let fields = block.fields();
193        // Normalize a bare-scalar `value` to the object form the
194        // renderer expects, so overrides always land as `{field: text}`.
195        ensure_object_value(env, &fields);
196        let block_prefix = format!("{prefix}.{bid}");
197        let Some(value_map) = env.get_mut("value").and_then(Value::as_object_mut) else {
198            continue;
199        };
200        for field in &fields {
201            match field {
202                BlockField::Widget { name, widget, .. } if widget.is_translatable_text() => {
203                    if let Some(ov) = translations
204                        .get(&format!("{block_prefix}.{name}"))
205                        .map(|s| s.trim())
206                        .filter(|s| !s.is_empty())
207                    {
208                        value_map.insert(name.clone(), Value::String(ov.to_owned()));
209                    }
210                }
211                BlockField::Stream { name, .. } | BlockField::Repeat { name, .. } => {
212                    if let Some(Value::Array(sub)) = value_map.get_mut(name) {
213                        apply_blocks(
214                            sub,
215                            &format!("{block_prefix}.{name}"),
216                            translations,
217                            dyn_set,
218                        );
219                    }
220                }
221                _ => {}
222            }
223        }
224    }
225}
226
227/// Normalize a block's `value` to an object dict. Mirrors the renderer's
228/// bare-scalar handling (`block::render::default_render`): a single-field
229/// block may store a bare scalar, which becomes `{first_field: scalar}`.
230fn normalize_value(value: Option<&Value>, fields: &[BlockField]) -> serde_json::Map<String, Value> {
231    match value {
232        Some(Value::Object(m)) => m.clone(),
233        Some(Value::Null) | None => serde_json::Map::new(),
234        Some(scalar) => {
235            let mut m = serde_json::Map::new();
236            if let Some(first) = fields.first() {
237                m.insert(first.name().to_owned(), scalar.clone());
238            }
239            m
240        }
241    }
242}
243
244/// Ensure `env["value"]` is an object in place, normalizing a bare
245/// scalar to `{first_field: scalar}` (and absent/null to `{}`).
246fn ensure_object_value(env: &mut Value, fields: &[BlockField]) {
247    if matches!(env.get("value"), Some(Value::Object(_))) {
248        return;
249    }
250    let scalar = env.get("value").cloned();
251    if let Some(obj) = env.as_object_mut() {
252        let mut m = serde_json::Map::new();
253        if let (Some(s), Some(first)) = (scalar, fields.first()) {
254            if !s.is_null() {
255                m.insert(first.name().to_owned(), s);
256            }
257        }
258        obj.insert("value".to_owned(), Value::Object(m));
259    }
260}
261
262#[cfg(test)]
263mod tests {
264    use super::*;
265    use crate::{register_block, Block};
266    use serde_json::json;
267
268    // --- Test blocks (registered into the inventory for the test bin) ---
269
270    #[derive(Default)]
271    struct TrCallout;
272    impl Block for TrCallout {
273        fn type_name(&self) -> &'static str {
274            "tr_callout"
275        }
276        fn verbose_name(&self) -> &'static str {
277            "Callout"
278        }
279        fn fields(&self) -> Vec<BlockField> {
280            vec![
281                BlockField::widget("tone", "Tone", WidgetKind::Select),
282                BlockField::widget("title", "Title", WidgetKind::Text),
283                BlockField::widget("body", "Body", WidgetKind::Markdown),
284            ]
285        }
286    }
287    register_block!(TrCallout);
288
289    #[derive(Default)]
290    struct TrParam;
291    impl Block for TrParam {
292        fn type_name(&self) -> &'static str {
293            "tr_param"
294        }
295        fn verbose_name(&self) -> &'static str {
296            "Param"
297        }
298        fn fields(&self) -> Vec<BlockField> {
299            vec![
300                BlockField::widget("name", "Name", WidgetKind::Text),
301                BlockField::widget("type_", "Type", WidgetKind::Text),
302                BlockField::widget("description", "Description", WidgetKind::Markdown),
303            ]
304        }
305    }
306    register_block!(TrParam);
307
308    #[derive(Default)]
309    struct TrApiRef;
310    impl Block for TrApiRef {
311        fn type_name(&self) -> &'static str {
312            "tr_api_reference"
313        }
314        fn verbose_name(&self) -> &'static str {
315            "API reference"
316        }
317        fn fields(&self) -> Vec<BlockField> {
318            vec![
319                BlockField::widget("symbol", "Symbol", WidgetKind::Text),
320                BlockField::widget("page", "Page", WidgetKind::PageChooser),
321                BlockField::repeat("params", "Params", "tr_param"),
322            ]
323        }
324    }
325    register_block!(TrApiRef);
326
327    #[derive(Default)]
328    struct TrMarkdown;
329    impl Block for TrMarkdown {
330        fn type_name(&self) -> &'static str {
331            "tr_markdown"
332        }
333        fn verbose_name(&self) -> &'static str {
334            "Markdown"
335        }
336        fn fields(&self) -> Vec<BlockField> {
337            vec![BlockField::widget("source", "Source", WidgetKind::Markdown)]
338        }
339    }
340    register_block!(TrMarkdown);
341
342    #[test]
343    fn collect_flat_skips_structural() {
344        let stream = json!([{
345            "type": "tr_callout", "id": "c1",
346            "value": {"tone": "info", "title": "Hello", "body": "world"}
347        }]);
348        let leaves = collect_translatable_leaves("body", &stream);
349        let paths: Vec<_> = leaves.iter().map(|l| l.path.as_str()).collect();
350        assert_eq!(paths, vec!["body.c1.title", "body.c1.body"]); // tone (Select) excluded
351        assert_eq!(leaves[0].canonical_text, "Hello");
352        assert_eq!(leaves[0].depth, 0);
353    }
354
355    #[test]
356    fn collect_nested_repeat() {
357        let stream = json!([{
358            "type": "tr_api_reference", "id": "a1",
359            "value": {
360                "symbol": "QuerySet", "page": 7,
361                "params": [
362                    {"type": "tr_param", "id": "p1", "value": {"name": "limit", "type_": "int", "description": "max rows"}},
363                    {"type": "tr_param", "id": "p2", "value": {"name": "offset", "type_": "int", "description": "skip rows"}}
364                ]
365            }
366        }]);
367        let leaves = collect_translatable_leaves("body", &stream);
368        let paths: Vec<_> = leaves.iter().map(|l| l.path.clone()).collect();
369        assert!(paths.contains(&"body.a1.symbol".to_owned()));
370        assert!(!paths.iter().any(|p| p.contains("page"))); // PageChooser excluded
371        assert!(paths.contains(&"body.a1.params.p1.name".to_owned()));
372        assert!(paths.contains(&"body.a1.params.p2.description".to_owned()));
373        // depth: top-level symbol=0, nested param fields=1
374        let symbol = leaves.iter().find(|l| l.path == "body.a1.symbol").unwrap();
375        assert_eq!(symbol.depth, 0);
376        let pname = leaves
377            .iter()
378            .find(|l| l.path == "body.a1.params.p1.name")
379            .unwrap();
380        assert_eq!(pname.depth, 1);
381    }
382
383    #[test]
384    fn collect_bare_scalar_single_field() {
385        let stream = json!([{"type": "tr_markdown", "id": "m1", "value": "# hi"}]);
386        let leaves = collect_translatable_leaves("body", &stream);
387        assert_eq!(leaves.len(), 1);
388        assert_eq!(leaves[0].path, "body.m1.source");
389        assert_eq!(leaves[0].canonical_text, "# hi");
390    }
391
392    #[test]
393    fn collect_drift_block_yields_nothing() {
394        let stream = json!([{"type": "totally_unknown", "id": "x1", "value": {"a": "b"}}]);
395        assert!(collect_translatable_leaves("body", &stream).is_empty());
396    }
397
398    #[test]
399    fn apply_round_trip_overrides_every_leaf() {
400        let stream = json!([{
401            "type": "tr_api_reference", "id": "a1",
402            "value": {
403                "symbol": "QuerySet", "page": 7,
404                "params": [{"type": "tr_param", "id": "p1", "value": {"name": "limit", "type_": "int", "description": "max"}}]
405            }
406        }]);
407        let tr = HashMap::from([
408            ("body.a1.symbol".to_owned(), "JeuRequête".to_owned()),
409            ("body.a1.params.p1.name".to_owned(), "limite".to_owned()),
410            (
411                "body.a1.params.p1.description".to_owned(),
412                "lignes max".to_owned(),
413            ),
414        ]);
415        let out = apply_translatable_overrides("body", &stream, &tr);
416        let block = &out[0]["value"];
417        assert_eq!(block["symbol"], "JeuRequête");
418        assert_eq!(block["page"], 7); // structural untouched
419        let p1 = &block["params"][0]["value"];
420        assert_eq!(p1["name"], "limite");
421        assert_eq!(p1["type_"], "int"); // not overridden → canonical
422        assert_eq!(p1["description"], "lignes max");
423        // ids + types preserved through the merge
424        assert_eq!(out[0]["id"], "a1");
425        assert_eq!(out[0]["value"]["params"][0]["id"], "p1");
426        assert_eq!(out[0]["value"]["params"][0]["type"], "tr_param");
427    }
428
429    #[test]
430    fn apply_partial_and_whitespace_fallback() {
431        let stream = json!([{"type": "tr_callout", "id": "c1", "value": {"tone": "info", "title": "Hello", "body": "world"}}]);
432        let tr = HashMap::from([
433            ("body.c1.title".to_owned(), "Bonjour".to_owned()),
434            ("body.c1.body".to_owned(), "   ".to_owned()), // whitespace-only → ignored
435        ]);
436        let out = apply_translatable_overrides("body", &stream, &tr);
437        assert_eq!(out[0]["value"]["title"], "Bonjour");
438        assert_eq!(out[0]["value"]["body"], "world"); // fallback to canonical
439    }
440
441    #[test]
442    fn apply_bare_scalar_written_as_object() {
443        let stream = json!([{"type": "tr_markdown", "id": "m1", "value": "# hi"}]);
444        let tr = HashMap::from([("body.m1.source".to_owned(), "# bonjour".to_owned())]);
445        let out = apply_translatable_overrides("body", &stream, &tr);
446        assert_eq!(out[0]["value"]["source"], "# bonjour"); // normalized to object form
447    }
448
449    #[test]
450    fn apply_stable_under_reorder() {
451        let mk = |id: &str, title: &str| json!({"type": "tr_callout", "id": id, "value": {"tone": "info", "title": title, "body": "b"}});
452        let tr = HashMap::from([("body.c2.title".to_owned(), "Deux".to_owned())]);
453        let a = json!([mk("c1", "One"), mk("c2", "Two")]);
454        let b = json!([mk("c2", "Two"), mk("c1", "One")]); // reversed
455        let oa = apply_translatable_overrides("body", &a, &tr);
456        let ob = apply_translatable_overrides("body", &b, &tr);
457        // c2 localized in both regardless of position
458        assert_eq!(oa[1]["value"]["title"], "Deux");
459        assert_eq!(ob[0]["value"]["title"], "Deux");
460    }
461
462    #[test]
463    fn apply_drift_passes_through() {
464        let stream = json!([{"type": "totally_unknown", "id": "x1", "value": {"a": "b"}}]);
465        let out = apply_translatable_overrides("body", &stream, &HashMap::new());
466        assert_eq!(out, stream);
467    }
468
469    #[test]
470    fn is_translatable_text_truth_table() {
471        assert!(WidgetKind::Text.is_translatable_text());
472        assert!(WidgetKind::Textarea.is_translatable_text());
473        assert!(WidgetKind::Markdown.is_translatable_text());
474        assert!(WidgetKind::RichText.is_translatable_text());
475        assert!(!WidgetKind::Select.is_translatable_text());
476        assert!(!WidgetKind::PageChooser.is_translatable_text());
477        assert!(!WidgetKind::Url.is_translatable_text());
478        assert!(!WidgetKind::Number.is_translatable_text());
479    }
480}