Support or document localization of messages and flags

[kamalmarhubi]

Make it easy for developers to support translations of their projects.

---

Current steps:

• Run cargo add clap -F string
• If using derive API
  • Replace field names being used as value names via #[arg(value_name = ...)]
• If using subcommands:
  • Replace Commands: header with a localized value via Command::subcommand_help_heading
  • Replace <COMMAND> value name with a localized value via Command::subcommand_value_name
• Replace Arguments and Options: headers with localized values via Command::next_help_heading and/or Arg::help_heading
• Disable the built-in flags (Command::disable_help_flag(false) and Command::disable_version_flag(false)) and provide your own versions (with ArgAction::Help, ArgAction::Version) with localized Arg::help
• Replace hard coded strings in help template (e.g. Usage) with a localized version via Command::help_template
  • Requires styling Usage manually
• Remove hard coded [] messages with Arg::hide_default_value, Arg::hide_possible_values, Arg::hide_env
• Fork clap::error::RichFormatter, replacing any hard coded strings with localized values. Use Error::apply to swap the formatter (e.g. use Parser::try_parse to get the error, call apply, and then err.exit())
• Replace in usages the collapsed optional named arguments placeholder [OPTIONS] by providing a custom usage with Command::override_usage

Unresolved:

• Getting the suggestion to run --help in errors, see How to make custom -h achieve the same effect as default -h #5409
• Manually writing usage and losing out on the adaptive usage in errors
• [aliases], [possible values], [default], [env], and Possible values: in help

Past examples:

• Migrate to clap, and localize usage & help text str4d/rage#442

[kbknapp]

This is something I'm interested in doing, but it will take some thought on how to best go about this. I'm putting it on the issue tracker, but let's get some discussion going on ways about this!

[kbknapp]

@kamalmarhubi I was thinking about this today, and would the YAML feature allow this? I.e. I'm thinking having a differente yaml file for each translation, and depending on which language/translation is compiled via features, you pick a different yaml file.

Example:

# Cargo.toml

[features]
default = ["en_US"]
en_US = []
es_ES = []

# en_US.yml
name: My Application
version: 1.0
about: An example using many languages
author: Kevin K. <kbknapp@gmail.com>
args:
    - opt:
        help: an example option
        short: o
        long: option
        multiple: true
        takes_value: true
    - pos:
        help: example positional with possible values
        index: 1
        possible_values:
            - fast
            - slow

# es_ES.yml
name: Mi Aplicacion
version: 1.0
about: Un ejamlo util muy idiomas
author: Kevin K. <kbknapp@gmail.com>
args:
    - opt:
        help: un ejamplo de un opcion
        short: o
        long: opcion
        multiple: true
        takes_value: true
    - pos:
        help: un ejamplo de un posicion con valores posible
        index: 1
        possible_values:
            - rapido
            - lento

// main.rs
#[cfg(feature = "en_US")]
const TRANSLATION: &'static str = "en_US.yml";

#[cfg(feature = "es_ES"]
const TRANSLATION: &'static str = "es_ES.yml";

fn main() {
    let yml = load_yaml!(TRANSLATION);
    let m = App::from_yaml(yml).get_matches();
}

Then depending on if you compile with --features en_US or --features es_ES it will set the translation. Does this work for you?

[kamalmarhubi]

Then depending on if you compile with --features en_US or --features es_ES it will set the translation. Does this work for you?

It's not me I'm thinking about, just something a user-facing system should allow for. :-)

And as for the solution, it would be much better to allow the user's locale settings to dictate the language in help. Requiring users to compile the tool with their language is non-ideal. Hooking into gettext or l20n would be a nice approach, as there's tooling for people to work on translations, and they can live outside of the binary.

[kamalmarhubi]

Though I guess there's a question of whether the options should be translated, or just the help... which comes up in your example. Thanks for that by the way, concrete is always good to look at!

[joshtriplett]

I've never seen a program that translates long option names; those are API, much like the names of functions in a library. Translating the help is a great idea, though.

I'd definitely agree with hooking into gettext, to work with the massive amount of translation infrastructure and tooling built around that, rather than creating a new translation format.

[hoodie]

I am currently trying to localize my app using crowbook-intl which is pretty nice. Unfortunately, the fact that AppMeta etc don't want to own the description strings makes it extremely hard to use dynamic strings in .about() and .help() methods. Do you have an idea to work around that? Could the next implementation perhaps own these strings?

[kbknapp]

@hoodie the strings only need to live as long as the App instance, so long as the localized strings are owned somewhere it shouldn't be an issue.

Can you paste some code that's giving issues and I can either see if there's a workaround or consider fixes if appropriate.

[hoodie]

infact you are right, it's just a bit tricky dealing with the lifetime constraints. I built so that app is immediately passed to a closure now.

[pksunkara]

This would also include localization of clap strings such Usage, Flags, etc..