locale, factor, shuf: Example of deferred locale loading for clap

src/uu/factor/src/factor.rs

@@ -15,7 +15,7 @@ use num_traits::FromPrimitive;
 use uucore::display::Quotable;
 use uucore::error::{FromIo, UResult, USimpleError, set_exit_code};
 use uucore::translate;
-use uucore::{format_usage, show_error, show_warning};
+use uucore::{show_error, show_warning};
 
 mod options {
     pub static EXPONENTS: &str = "exponents";
@@ -148,7 +148,7 @@ fn write_result_big_uint(
 
 #[uucore::main]
 pub fn uumain(args: impl uucore::Args) -> UResult<()> {
-    let matches = uucore::clap_localization::handle_clap_result(uu_app(), args)?;
+    let matches = uucore::clap_localization::parse_deferred(uu_app_base, args)?;
 
     // If matches find --exponents flag than variable print_exponents is true and p^e output format will be used.
     let print_exponents = matches.get_flag(options::EXPONENTS);
@@ -188,11 +188,12 @@ pub fn uumain(args: impl uucore::Args) -> UResult<()> {
 }
 
 pub fn uu_app() -> Command {
+    uucore::clap_localization::localize_command(uu_app_base())
+}
+
+fn uu_app_base() -> Command {
     Command::new(uucore::util_name())
         .version(uucore::crate_version!())
-        .help_template(uucore::localized_help_template(uucore::util_name()))
-        .about(translate!("factor-about"))
-        .override_usage(format_usage(&translate!("factor-usage")))
         .infer_long_args(true)
         .disable_help_flag(true)
         .args_override_self(true)
@@ -201,13 +202,11 @@ pub fn uu_app() -> Command {
             Arg::new(options::EXPONENTS)
                 .short('h')
                 .long(options::EXPONENTS)
-                .help(translate!("factor-help-exponents"))
                 .action(ArgAction::SetTrue),
         )
         .arg(
             Arg::new(options::HELP)
                 .long(options::HELP)
-                .help(translate!("factor-help-help"))
                 .action(ArgAction::Help),
         )
 }

src/uu/shuf/src/shuf.rs

@@ -21,7 +21,6 @@ use rand::{
 
 use uucore::display::{OsWrite, Quotable};
 use uucore::error::{FromIo, UResult, USimpleError, UUsageError};
-use uucore::format_usage;
 use uucore::translate;
 
 mod compat_random_source;
@@ -68,7 +67,7 @@ mod options {
 
 #[uucore::main]
 pub fn uumain(args: impl uucore::Args) -> UResult<()> {
-    let matches = uucore::clap_localization::handle_clap_result(uu_app(), args)?;
+    let matches = uucore::clap_localization::parse_deferred(uu_app_base, args)?;
 
     let mode = if matches.get_flag(options::ECHO) {
         Mode::Echo(
@@ -172,17 +171,17 @@ pub fn uumain(args: impl uucore::Args) -> UResult<()> {
 }
 
 pub fn uu_app() -> Command {
+    uucore::clap_localization::localize_command(uu_app_base())
+}
+
+fn uu_app_base() -> Command {
     Command::new(uucore::util_name())
-        .about(translate!("shuf-about"))
         .version(uucore::crate_version!())
-        .help_template(uucore::localized_help_template(uucore::util_name()))
-        .override_usage(format_usage(&translate!("shuf-usage")))
         .infer_long_args(true)
         .arg(
             Arg::new(options::ECHO)
                 .short('e')
                 .long(options::ECHO)
-                .help(translate!("shuf-help-echo"))
                 .action(ArgAction::SetTrue)
                 .overrides_with(options::ECHO)
                 .conflicts_with(options::INPUT_RANGE),
@@ -192,7 +191,6 @@ pub fn uu_app() -> Command {
                 .short('i')
                 .long(options::INPUT_RANGE)
                 .value_name("LO-HI")
-                .help(translate!("shuf-help-input-range"))
                 .value_parser(parse_range)
                 .conflicts_with(options::FILE_OR_ARGS),
         )
@@ -202,23 +200,20 @@ pub fn uu_app() -> Command {
                 .long(options::HEAD_COUNT)
                 .value_name("COUNT")
                 .action(ArgAction::Append)
-                .help(translate!("shuf-help-head-count"))
                 .value_parser(u64::from_str),
         )
         .arg(
             Arg::new(options::OUTPUT)
                 .short('o')
                 .long(options::OUTPUT)
                 .value_name("FILE")
-                .help(translate!("shuf-help-output"))
                 .value_parser(ValueParser::path_buf())
                 .value_hint(clap::ValueHint::FilePath),
         )
         .arg(
             Arg::new(options::RANDOM_SEED)
                 .long(options::RANDOM_SEED)
                 .value_name("STRING")
-                .help(translate!("shuf-help-random-seed"))
                 .value_parser(ValueParser::string())
                 .value_hint(clap::ValueHint::Other)
                 .conflicts_with(options::RANDOM_SOURCE),
@@ -227,23 +222,20 @@ pub fn uu_app() -> Command {
             Arg::new(options::RANDOM_SOURCE)
                 .long(options::RANDOM_SOURCE)
                 .value_name("FILE")
-                .help(translate!("shuf-help-random-source"))
                 .value_parser(ValueParser::path_buf())
                 .value_hint(clap::ValueHint::FilePath),
         )
         .arg(
             Arg::new(options::REPEAT)
                 .short('r')
                 .long(options::REPEAT)
-                .help(translate!("shuf-help-repeat"))
                 .action(ArgAction::SetTrue)
                 .overrides_with(options::REPEAT),
         )
         .arg(
             Arg::new(options::ZERO_TERMINATED)
                 .short('z')
                 .long(options::ZERO_TERMINATED)
-                .help(translate!("shuf-help-zero-terminated"))
                 .action(ArgAction::SetTrue)
                 .overrides_with(options::ZERO_TERMINATED),
         )

src/uucore/src/lib/lib.rs

@@ -263,7 +263,7 @@ pub fn format_usage(s: &str) -> String {
 /// let app = Command::new("myutil")
 ///     .help_template(localized_help_template("myutil"));
 /// ```
-pub fn localized_help_template(util_name: &str) -> clap::builder::StyledStr {
+pub fn localized_help_template(_util_name: &str) -> clap::builder::StyledStr {
     use std::io::IsTerminal;
 
     // Determine if colors should be enabled - same logic as configure_localized_command
@@ -276,20 +276,14 @@ pub fn localized_help_template(util_name: &str) -> clap::builder::StyledStr {
             && std::env::var("TERM").unwrap_or_default() != "dumb"
     };
 
-    localized_help_template_with_colors(util_name, colors_enabled)
+    localized_help_template_with_colors(colors_enabled)
 }
 
 /// Create a localized help template with explicit color control
 /// This ensures color detection consistency between clap and our template
-pub fn localized_help_template_with_colors(
-    util_name: &str,
-    colors_enabled: bool,
-) -> clap::builder::StyledStr {
+pub fn localized_help_template_with_colors(colors_enabled: bool) -> clap::builder::StyledStr {
     use std::fmt::Write;
 
-    // Ensure localization is initialized for this utility
-    let _ = locale::setup_localization(util_name);
-
     // Get the localized "Usage" label
     let usage_label = crate::locale::translate!("common-usage");
 

src/uucore/src/lib/mods/clap_localization.rs

@@ -516,13 +516,54 @@ pub fn configure_localized_command(mut cmd: Command) -> Command {
     // For help output (stdout), we check stdout TTY status
     let colors_enabled = should_use_color_for_stream(&std::io::stdout());
 
-    cmd = cmd.help_template(crate::localized_help_template_with_colors(
-        crate::util_name(),
-        colors_enabled,
-    ));
+    cmd = cmd.help_template(crate::localized_help_template_with_colors(colors_enabled));
     cmd
 }
 
+/// Apply localized about, usage, help template, and per-arg help to a
+/// `Command` using the naming convention `{name}-about`, `{name}-usage`,
+/// `{name}-help-{arg_id}`.
+pub fn localize_command(mut cmd: Command) -> Command {
+    let name = cmd.get_name().to_string();
+
+    cmd = cmd
+        .about(crate::locale::get_message(&format!("{name}-about")))
+        .override_usage(crate::format_usage(&crate::locale::get_message(&format!(
+            "{name}-usage"
+        ))))
+        .help_template(crate::localized_help_template(&name));
+
+    let arg_ids: Vec<String> = cmd
+        .get_arguments()
+        .map(|a| a.get_id().to_string())
+        .collect();
+
+    for arg_id in arg_ids {
+        let help_key = format!("{name}-help-{arg_id}");
+        let help_text = crate::locale::get_message(&help_key);
+        if help_text != help_key {
+            cmd = cmd.mut_arg(&arg_id, |a| a.help(help_text));
+        }
+    }
+
+    cmd
+}
+
+/// Parse arguments with deferred translation loading. On the happy path,
+/// no FTL files are loaded. `app_fn` should build a bare `Command` without
+/// `translate!()` calls; translations are applied via `localize_command`
+/// only when help or error output is needed.
+pub fn parse_deferred<F>(app_fn: F, args: impl crate::Args) -> UResult<ArgMatches>
+where
+    F: Fn() -> Command,
+{
+    let args: Vec<OsString> = args.collect();
+    match app_fn().try_get_matches_from(args.iter().map(Clone::clone)) {
+        Ok(m) => Ok(m),
+        Err(_) => handle_clap_result(localize_command(app_fn()), args),
+    }
+}
+
 /* spell-checker: disable */
 #[cfg(test)]
 mod tests {