feat(duration): add Duration#humanize with I18n-compatible compound units

Adds Duration.humanize(locale?) instance method that renders a duration
as a human-readable compound string ("1 hour 1 minute", "16 minutes
40 seconds"). Selects best unit(s) based on magnitude: minutes+seconds
for sub-hour, hours+minutes for sub-day, days+hours for longer.

Uses I18n.translate with {count} interpolation for localization;
falls back to English plurals when no translation key is found.
Accepts optional locale override; defaults to current I18n locale.

Also adds duration.seconds/minutes/hours/days fallback keys to
template/config/locales/en.yml.

Closes tasks/todo/add-duration-humanize-instance-method-i18n-compatible-compound-units.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Olivier Bonnaure

src/interpreter/builtins/datetime_class.rs

@@ -9,6 +9,7 @@ use std::rc::Rc;
 
 use chrono::{Datelike, Local, Timelike};
 
+use super::i18n::helpers::{get_locale as i18n_get_locale, interpolate, lookup_translation};
 use crate::interpreter::environment::Environment;
 use crate::interpreter::value::{Class, Instance, NativeFunction, Value};
 
@@ -64,6 +65,117 @@ fn parse_datetime_string(s: &str) -> Result<i64, String> {
     }
 }
 
+fn humanize_duration(seconds: f64, locale: &str) -> String {
+    let total_secs = seconds.abs();
+    let (primary_unit, primary_count, secondary_count) = if total_secs < 60.0 {
+        ("seconds", total_secs as i64, 0)
+    } else if total_secs < 3600.0 {
+        let minutes = (total_secs / 60.0).floor();
+        let remaining_secs = (total_secs % 60.0).floor();
+        (
+            "minutes",
+            minutes as i64,
+            if remaining_secs > 0.0 {
+                remaining_secs as i64
+            } else {
+                0
+            },
+        )
+    } else if total_secs < 86400.0 {
+        let hours = (total_secs / 3600.0).floor();
+        let remaining_mins = ((total_secs % 3600.0) / 60.0).floor();
+        (
+            "hours",
+            hours as i64,
+            if remaining_mins > 0.0 {
+                remaining_mins as i64
+            } else {
+                0
+            },
+        )
+    } else {
+        let days = (total_secs / 86400.0).floor();
+        let remaining_hrs = ((total_secs % 86400.0) / 3600.0).floor();
+        (
+            "days",
+            days as i64,
+            if remaining_hrs > 0.0 {
+                remaining_hrs as i64
+            } else {
+                0
+            },
+        )
+    };
+    let key = format!("duration.{}", primary_unit);
+    let primary_translated = lookup_translation(locale, &key).unwrap_or_else(|| {
+        let count_str = primary_count.to_string();
+        match primary_unit {
+            "seconds" => format!(
+                "{} second{}",
+                count_str,
+                if primary_count == 1 { "" } else { "s" }
+            ),
+            "minutes" => format!(
+                "{} minute{}",
+                count_str,
+                if primary_count == 1 { "" } else { "s" }
+            ),
+            "hours" => format!(
+                "{} hour{}",
+                count_str,
+                if primary_count == 1 { "" } else { "s" }
+            ),
+            "days" => format!(
+                "{} day{}",
+                count_str,
+                if primary_count == 1 { "" } else { "s" }
+            ),
+            _ => format!("{} {}", count_str, primary_unit),
+        }
+    });
+    let primary_formatted = interpolate(
+        &primary_translated,
+        &[("count".to_string(), primary_count.to_string())],
+    );
+    if secondary_count > 0 {
+        let sec_key = if primary_unit == "minutes" {
+            "seconds"
+        } else if primary_unit == "hours" {
+            "minutes"
+        } else {
+            "hours"
+        };
+        let secondary_translated = lookup_translation(locale, sec_key).unwrap_or_else(|| {
+            let count_str = secondary_count.to_string();
+            match sec_key {
+                "seconds" => format!(
+                    "{} second{}",
+                    count_str,
+                    if secondary_count == 1 { "" } else { "s" }
+                ),
+                "minutes" => format!(
+                    "{} minute{}",
+                    count_str,
+                    if secondary_count == 1 { "" } else { "s" }
+                ),
+                "hours" => format!(
+                    "{} hour{}",
+                    count_str,
+                    if secondary_count == 1 { "" } else { "s" }
+                ),
+                _ => format!("{} {}", count_str, sec_key),
+            }
+        });
+        let secondary_formatted = interpolate(
+            &secondary_translated,
+            &[("count".to_string(), secondary_count.to_string())],
+        );
+        format!("{} {}", primary_formatted, secondary_formatted)
+    } else {
+        primary_formatted
+    }
+}
+
 pub fn register_datetime_and_duration_classes(env: &mut Environment) {
     // Build DateTime instance methods
     let mut dt_native_methods: HashMap<String, Rc<NativeFunction>> = HashMap::new();
@@ -408,6 +520,35 @@ pub fn register_datetime_and_duration_classes(env: &mut Environment) {
         })),
     );
 
+    dur_native_methods.insert(
+        String::from("humanize"),
+        Rc::new(NativeFunction::new(
+            "Duration.humanize",
+            None,
+            move |args| {
+                let this = match args.first() {
+                    Some(Value::Instance(inst)) => inst,
+                    _ => return Err("Duration.humanize() called on non-Duration".to_string()),
+                };
+                let locale = if args.len() > 1 {
+                    match &args[1] {
+                        Value::String(s) => s.clone(),
+                        Value::Null => i18n_get_locale(),
+                        _ => return Err("Duration.humanize() locale must be a string".to_string()),
+                    }
+                } else {
+                    i18n_get_locale()
+                };
+                let seconds = match this.borrow().fields.get("seconds").cloned() {
+                    Some(Value::Float(s)) => s,
+                    Some(Value::Int(s)) => s as f64,
+                    _ => return Err("Duration missing seconds".to_string()),
+                };
+                Ok(Value::String(humanize_duration(seconds, &locale)))
+            },
+        )),
+    );
+
     // Clone for use in instance methods that create new DateTime instances
     let dt_methods_for_add_days = dt_native_methods.clone();
     let dt_methods_for_add_hours = dt_native_methods.clone();

template/config/locales/en.yml

@@ -13,3 +13,8 @@ en:
   app:
     welcome: Welcome
     greeting: "Hello, {name}!"
+  duration:
+    seconds: "{count} second{count}"
+    minutes: "{count} minute{count}"
+    hours: "{count} hour{count}"
+    days: "{count} day{count}"

www/app/views/docs/builtins/duration.html.slv

@@ -217,6 +217,31 @@ println(duration.total_days())  # 7</code></pre>
 println(duration.to_string())  # "3661s"</code></pre>
             </div>
         </section>
+
+        <section id="def-humanize" class="scroll-mt-20 mb-6">
+            <div class="rounded-xl bg-white/5 border border-white/10 p-5">
+                <a href="#def-humanize" class="group flex items-center gap-2 mb-3">
+                    <code class="text-lg font-mono text-indigo-400">.humanize(locale?)</code>
+                    <svg class="w-4 h-4 opacity-0 group-hover:opacity-100 text-gray-500 transition-opacity" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1" />
+                    </svg>
+                </a>
+                <p class="text-gray-400 mb-3">Get the duration as a human-readable compound string (e.g., "1 hour 1 minute"). Selects the most appropriate unit(s) based on the duration length.</p>
+                <h4 class="text-sm font-semibold text-gray-300 mt-4 mb-2">Parameters</h4>
+                <div class="text-sm text-gray-400">
+                    <code class="text-amber-400">locale</code> : <code class="text-purple-400">String?</code> - Optional locale code (defaults to current I18n locale)
+                </div>
+                <h4 class="text-sm font-semibold text-gray-300 mt-4 mb-2">Returns</h4>
+                <div class="text-sm text-gray-400">
+                    <code class="text-purple-400">String</code> - Humanized duration string
+                </div>
+                <pre data-filename="Example"><code class="language-soli text-sm">Duration.seconds(3661).humanize()   # "1 hour 1 minute"
+Duration.seconds(1000).humanize()  # "16 minutes 40 seconds"
+Duration.seconds(7200).humanize()  # "2 hours"
+Duration.seconds(90).humanize()    # "1 minute 30 seconds"
+Duration.minutes(5).humanize()      # "5 minutes"</code></pre>
+            </div>
+        </section>
     </section>
 
     <!-- Complete Example -->

www/docs/builtins.md

@@ -2191,6 +2191,25 @@ duration = Duration.of_seconds(3661)
 println(duration.to_string())  # "3661s"
 ```
 
+#### .humanize(locale?)
+
+Gets the duration as a human-readable compound string (e.g., "1 hour 1 minute"). Selects the most appropriate unit(s) based on the duration length — for sub-hour durations it combines minutes + seconds; for sub-day it combines hours + minutes; for longer durations it combines days + hours. The optional locale parameter overrides the current I18n locale for translation.
+
+**Parameters:**
+- `locale` (String, optional) - Locale code for translation (defaults to current I18n locale)
+
+**Returns:** String
+
+**Example:**
+```soli
+Duration.seconds(3661).humanize()    # "1 hour 1 minute"
+Duration.seconds(1000).humanize()   # "16 minutes 40 seconds"
+Duration.seconds(7200).humanize()   # "2 hours"
+Duration.seconds(90).humanize()     # "1 minute 30 seconds"
+Duration.minutes(5).humanize()       # "5 minutes"
+Duration.humanize("fr")             # respects fr locale if translations exist
+```
+
 ### Complete Example
 
 ```soli