POC of Approach to Supporting Internationalization

Cargo.toml

@@ -189,6 +189,8 @@ snapbox = "0.6.16"
 shlex = "1.3.0"
 automod = "1.0.14"
 clap-cargo = { version = "0.14.1", default-features = false }
+rust-i18n = "3.1.2"
+serde_yml = "0.0.12"
 
 [[example]]
 name = "demo"
@@ -505,6 +507,12 @@ path = "examples/derive_ref/flatten_hand_args.rs"
 required-features = ["derive"]
 doc-scrape-examples = true
 
+[[example]]
+name = "i18n"
+path = "examples/i18n/main.rs"
+required-features = ["derive"]
+doc-scrape-examples = true
+
 [profile.test]
 opt-level = 1
 

clap_bench/benches/complex.rs

@@ -1,6 +1,6 @@
 #![allow(elided_lifetimes_in_paths)] // needed for divan
 
-use clap::{arg, ArgMatches, Command};
+use clap::{arg, text_provider::DEFAULT_TEXT_PROVIDER, ArgMatches, Command};
 
 macro_rules! create_app {
     () => {{
@@ -48,7 +48,7 @@ fn build() -> Command {
 
 #[divan::bench(args=COMPLEX_ARGS)]
 fn startup(args: &Args) -> ArgMatches {
-    create_app!().get_matches_from(args.args())
+    create_app!().get_matches_from(args.args(), &*DEFAULT_TEXT_PROVIDER)
 }
 
 #[divan::bench]

clap_bench/benches/empty.rs

@@ -1,5 +1,6 @@
 #![allow(elided_lifetimes_in_paths)] // needed for divan
 
+use clap::text_provider::DEFAULT_TEXT_PROVIDER;
 use clap::ArgMatches;
 use clap::Command;
 
@@ -16,7 +17,7 @@ fn build() -> Command {
 
 #[divan::bench]
 fn startup() -> ArgMatches {
-    create_app!().get_matches_from(vec![""])
+    create_app!().get_matches_from(vec![""], &*DEFAULT_TEXT_PROVIDER)
 }
 
 #[divan::bench]

clap_bench/benches/ripgrep.rs

@@ -41,11 +41,13 @@ mod render_help {
 }
 
 mod startup {
+    use clap::text_provider::DEFAULT_TEXT_PROVIDER;
+
     use super::{app_short, ArgMatches};
 
     #[divan::bench]
     fn simple() -> ArgMatches {
-        app_short().get_matches_from(vec!["rg", "pat"])
+        app_short().get_matches_from(vec!["rg", "pat"], &*DEFAULT_TEXT_PROVIDER)
     }
 
     #[divan::bench]
@@ -62,7 +64,7 @@ mod startup {
             "-C5",
             "--follow",
             "-e some",
-        ])
+        ], &*DEFAULT_TEXT_PROVIDER)
     }
 
     #[divan::bench]
@@ -228,7 +230,7 @@ mod startup {
             "some", "some", "some", "some", "some", "some", "some", "some", "some", "some", "some",
             "some", "some", "some", "some", "some", "some", "some", "some", "some", "some", "some",
             "some", "some", "some", "some", "some", "some", "some",
-        ])
+        ], &*DEFAULT_TEXT_PROVIDER)
     }
 }
 

clap_bench/benches/rustup.rs

@@ -12,16 +12,18 @@ fn build() -> Command {
 }
 
 mod startup {
+    use clap::text_provider::DEFAULT_TEXT_PROVIDER;
+
     use super::{build_cli, ArgMatches};
 
     #[divan::bench]
     fn empty() -> ArgMatches {
-        build_cli().get_matches_from([""])
+        build_cli().get_matches_from([""], &*DEFAULT_TEXT_PROVIDER)
     }
 
     #[divan::bench]
     fn sc() -> ArgMatches {
-        build_cli().get_matches_from(["rustup override add stable"])
+        build_cli().get_matches_from(["rustup override add stable"], &*DEFAULT_TEXT_PROVIDER)
     }
 }
 

clap_bench/benches/simple.rs

@@ -20,21 +20,23 @@ fn build() -> Command {
 }
 
 mod startup {
+    use clap::text_provider::DEFAULT_TEXT_PROVIDER;
+
     use super::{arg, ArgMatches, Command};
 
     #[divan::bench]
     fn flag() -> ArgMatches {
-        create_app!().get_matches_from(vec!["myprog", "-f"])
+        create_app!().get_matches_from(vec!["myprog", "-f"], &*DEFAULT_TEXT_PROVIDER)
     }
 
     #[divan::bench]
     fn opt() -> ArgMatches {
-        create_app!().get_matches_from(vec!["myprog", "-o", "option1"])
+        create_app!().get_matches_from(vec!["myprog", "-o", "option1"], &*DEFAULT_TEXT_PROVIDER)
     }
 
     #[divan::bench]
     fn pos() -> ArgMatches {
-        create_app!().get_matches_from(vec!["myprog", "arg1"])
+        create_app!().get_matches_from(vec!["myprog", "arg1"], &*DEFAULT_TEXT_PROVIDER)
     }
 }
 

clap_builder/Cargo.toml

@@ -67,6 +67,8 @@ anstyle = "1.0.8"
 terminal_size = { version = "0.4.0", optional = true }
 backtrace = { version = "0.3.73", optional = true }
 unicode-width = { version = "0.2.0", optional = true }
+serde_yml = "0.0.12"
+lazy_static = "1.5.0"
 
 [dev-dependencies]
 static_assertions = "1.1.0"

clap_builder/src/builder/command.rs

@@ -26,6 +26,8 @@ use crate::mkeymap::MKeyMap;
 use crate::output::fmt::Stream;
 use crate::output::{fmt::Colorizer, write_help, Usage};
 use crate::parser::{ArgMatcher, ArgMatches, Parser};
+use crate::text_provider::TextProvider;
+use crate::text_provider::DEFAULT_TEXT_PROVIDER;
 use crate::util::ChildGraph;
 use crate::util::{color::ColorChoice, Id};
 use crate::{Error, INTERNAL_ERROR_MSG};
@@ -609,8 +611,8 @@ impl Command {
     /// [`env::args_os`]: std::env::args_os()
     /// [`Command::try_get_matches_from_mut`]: Command::try_get_matches_from_mut()
     #[inline]
-    pub fn get_matches(self) -> ArgMatches {
-        self.get_matches_from(env::args_os())
+    pub fn get_matches(self, texts: &impl TextProvider) -> ArgMatches {
+        self.get_matches_from(env::args_os(), texts)
     }
 
     /// Parse [`env::args_os`], [exiting][Error::exit] on failure.
@@ -633,9 +635,9 @@ impl Command {
     /// ```
     /// [`env::args_os`]: std::env::args_os()
     /// [`Command::get_matches`]: Command::get_matches()
-    pub fn get_matches_mut(&mut self) -> ArgMatches {
+    pub fn get_matches_mut(&mut self, texts: &impl TextProvider) -> ArgMatches {
         self.try_get_matches_from_mut(env::args_os())
-            .unwrap_or_else(|e| e.exit())
+            .unwrap_or_else(|e| e.exit(texts))
     }
 
     /// Parse [`env::args_os`], returning a [`clap::Result`] on failure.
@@ -704,14 +706,14 @@ impl Command {
     /// [`Command::get_matches`]: Command::get_matches()
     /// [`clap::Result`]: Result
     /// [`Vec`]: std::vec::Vec
-    pub fn get_matches_from<I, T>(mut self, itr: I) -> ArgMatches
+    pub fn get_matches_from<I, T>(mut self, itr: I, texts: &impl TextProvider) -> ArgMatches
     where
         I: IntoIterator<Item = T>,
         T: Into<OsString> + Clone,
     {
         self.try_get_matches_from_mut(itr).unwrap_or_else(|e| {
             drop(self);
-            e.exit()
+            e.exit(texts)
         })
     }
 
@@ -814,7 +816,6 @@ impl Command {
     {
         let mut raw_args = clap_lex::RawArgs::new(itr);
         let mut cursor = raw_args.cursor();
-
         if self.settings.is_set(AppSettings::Multicall) {
             if let Some(argv0) = raw_args.next_os(&mut cursor) {
                 let argv0 = Path::new(&argv0);
@@ -878,6 +879,8 @@ impl Command {
         let usage = Usage::new(self);
         write_help(&mut styled, self, &usage, false);
 
+        styled.render_text(&*DEFAULT_TEXT_PROVIDER);
+
         let c = Colorizer::new(Stream::Stdout, color).with_content(styled);
         c.print()
     }
@@ -905,7 +908,7 @@ impl Command {
         let mut styled = StyledStr::new();
         let usage = Usage::new(self);
         write_help(&mut styled, self, &usage, true);
-
+        styled.render_text(&*DEFAULT_TEXT_PROVIDER);
         let c = Colorizer::new(Stream::Stdout, color).with_content(styled);
         c.print()
     }
@@ -4278,7 +4281,9 @@ impl Command {
 
         // do the real parsing
         let mut parser = Parser::new(self);
+
         if let Err(error) = parser.get_matches_with(&mut matcher, raw_args, args_cursor) {
+
             if self.is_set(AppSettings::IgnoreErrors) && error.use_stderr() {
                 debug!("Command::_do_parse: ignoring error: {error}");
             } else {
@@ -4729,7 +4734,7 @@ impl Command {
                     .help("Print help (see more with '--help')")
                     .long_help("Print help (see a summary with '-h')");
             } else {
-                arg = arg.help("Print help");
+                arg = arg.help("{clap.help.short-help}");
             }
             // Avoiding `arg_internal` to not be sensitive to `next_help_heading` /
             // `next_display_order`
@@ -4741,15 +4746,15 @@ impl Command {
                 .short('V')
                 .long("version")
                 .action(ArgAction::Version)
-                .help("Print version");
+                .help("{clap.version.short-help}");
             // Avoiding `arg_internal` to not be sensitive to `next_help_heading` /
             // `next_display_order`
             self.args.push(arg);
         }
 
         if !self.is_set(AppSettings::DisableHelpSubcommand) {
             debug!("Command::_check_help_and_version: Building help subcommand");
-            let help_about = "Print this message or the help of the given subcommand(s)";
+            let help_about = "{clap.help.about}";
 
             let mut help_subcmd = if expand_help_tree {
                 // Slow code path to recursively clone all other subcommand subtrees under help
@@ -4771,7 +4776,7 @@ impl Command {
                     Arg::new("subcommand")
                         .action(ArgAction::Append)
                         .num_args(..)
-                        .value_name("COMMAND")
+                        .value_name("{clap.help.command.value-name}")
                         .help("Print help for the subcommand(s)"),
                 )
             };

clap_builder/src/builder/styled_str.rs

@@ -1,5 +1,7 @@
 #![cfg_attr(not(feature = "usage"), allow(dead_code))]
 
+use crate::{text_provider::TextProvider, util::interpolate};
+
 /// Terminal-styling container
 ///
 /// Styling may be encoded as [ANSI Escape Code](https://en.wikipedia.org/wiki/ANSI_escape_code)
@@ -29,6 +31,11 @@ impl StyledStr {
         Self(String::new())
     }
 
+    /// Interpolate values into the text
+    pub fn render_text(&mut self, texts: &impl TextProvider) {
+        self.0 = interpolate(&self.0, texts);
+    }
+
     /// Display using [ANSI Escape Code](https://en.wikipedia.org/wiki/ANSI_escape_code) styling
     #[cfg(feature = "color")]
     pub fn ansi(&self) -> impl std::fmt::Display + '_ {

clap_builder/src/derive.rs

@@ -2,6 +2,7 @@
 //! macros in `clap_derive`.
 
 use crate::builder::PossibleValue;
+use crate::text_provider::{TextProvider, DEFAULT_TEXT_PROVIDER};
 use crate::{ArgMatches, Command, Error};
 
 use std::ffi::OsString;
@@ -28,15 +29,22 @@ use std::ffi::OsString;
 pub trait Parser: FromArgMatches + CommandFactory + Sized {
     /// Parse from `std::env::args_os()`, [exit][Error::exit] on error.
     fn parse() -> Self {
-        let mut matches = <Self as CommandFactory>::command().get_matches();
+        Self::parse_with_texts(&*DEFAULT_TEXT_PROVIDER)
+    }
+
+    /// Parse from `std::env::args_os()`, [exit][Error::exit] on error, but replace the default Clap [`TextProvider`] with
+    /// a custom implementation.
+    fn parse_with_texts(texts: &impl TextProvider) -> Self {
+        let mut matches = <Self as CommandFactory>::command().get_matches(texts);
         let res = <Self as FromArgMatches>::from_arg_matches_mut(&mut matches)
             .map_err(format_error::<Self>);
+
         match res {
             Ok(s) => s,
             Err(e) => {
                 // Since this is more of a development-time error, we aren't doing as fancy of a quit
                 // as `get_matches`
-                e.exit()
+                e.exit(texts)
             }
         }
     }
@@ -48,20 +56,20 @@ pub trait Parser: FromArgMatches + CommandFactory + Sized {
     }
 
     /// Parse from iterator, [exit][Error::exit] on error.
-    fn parse_from<I, T>(itr: I) -> Self
+    fn parse_from<I, T>(itr: I, texts: &impl TextProvider) -> Self
     where
         I: IntoIterator<Item = T>,
         T: Into<OsString> + Clone,
     {
-        let mut matches = <Self as CommandFactory>::command().get_matches_from(itr);
+        let mut matches = <Self as CommandFactory>::command().get_matches_from(itr, texts);
         let res = <Self as FromArgMatches>::from_arg_matches_mut(&mut matches)
             .map_err(format_error::<Self>);
         match res {
             Ok(s) => s,
             Err(e) => {
                 // Since this is more of a development-time error, we aren't doing as fancy of a quit
                 // as `get_matches_from`
-                e.exit()
+                e.exit(texts)
             }
         }
     }
@@ -81,18 +89,18 @@ pub trait Parser: FromArgMatches + CommandFactory + Sized {
     /// Unlike [`Parser::parse`], this works with an existing instance of `self`.
     /// The assumption is that all required fields are already provided and any [`Args`] or
     /// [`Subcommand`]s provided by the user will modify only what is specified.
-    fn update_from<I, T>(&mut self, itr: I)
+    fn update_from<I, T>(&mut self, itr: I, texts: &impl TextProvider)
     where
         I: IntoIterator<Item = T>,
         T: Into<OsString> + Clone,
     {
-        let mut matches = <Self as CommandFactory>::command_for_update().get_matches_from(itr);
+        let mut matches = <Self as CommandFactory>::command_for_update().get_matches_from(itr, texts);
         let res = <Self as FromArgMatches>::update_from_arg_matches_mut(self, &mut matches)
             .map_err(format_error::<Self>);
         if let Err(e) = res {
             // Since this is more of a development-time error, we aren't doing as fancy of a quit
             // as `get_matches_from`
-            e.exit()
+            e.exit(texts)
         }
     }
 
@@ -321,12 +329,12 @@ impl<T: Parser> Parser for Box<T> {
         <T as Parser>::try_parse().map(Box::new)
     }
 
-    fn parse_from<I, It>(itr: I) -> Self
+    fn parse_from<I, It>(itr: I, texts: &impl TextProvider) -> Self
     where
         I: IntoIterator<Item = It>,
         It: Into<OsString> + Clone,
     {
-        Box::new(<T as Parser>::parse_from(itr))
+        Box::new(<T as Parser>::parse_from(itr, texts))
     }
 
     fn try_parse_from<I, It>(itr: I) -> Result<Self, Error>