Skip to content

Conversation

@lordeji
Copy link

@lordeji lordeji commented Nov 19, 2025

I chose to create a draft and not a PR because the changes are mainly to uucore but would need to be applied to all packages one by one.
Before doing this task, I prefer waiting for a validation on the changes of uucore.
It's my first PR ever so don't hesitate to correct me if my way of doing this is wrong or if you need me to add more documentation or testing etc.


This draft focus on making the clap localization system more complete :

  1. Unify the localization --help and --version by using the locale id from uccore which would fix l10n: text for --help & --version options is not localized #8923 and would also clean the many instances of manual writing of help and version texts.

Packages that manually implement only help : chcon, chgrp, chmod, chown, df, du, factor, ls, nl, od, pinky, pr, tee, touch.
Packages that manually implement help and version : expr, false, printf, sort, true.

  1. Localize titles in help template.
  2. Localize the options with default descriptions by translating the word "Default" and adding quotes around values for better readibility

I also deleted the configure_localized_command() function because it seems to be a legacy function that is used in some packages but is now replaced by .help_template(uucore::localized_help_template()) (and with my draft, it would ultimately be replaced by .localize_help_template()).

Packages using the legacy function : base32, base64, basenc (all 3 use a common config at base32/src/base_common.rs), chcon, chgrp, chroot, expand, ls, pinky, printenv, runcon, sort, tty, uniq, who

Caveats

The main problem is that my functions are position dependant in uu_app().

  1. .localize_help_and_version() must be called after all arguments or it won't appear as the last options in the help text.
  2. For .localize_help_template(), there is no way to localize at compile time so it checks what type of argument is present and print the section title accordingly but for the checks to be valid, the arguments must be set before.
  3. Kind of the same for .help_localized(), if the default value is not set before calling the function then the default values won't be displayed.

Not really a problem but could lead to incomprehensible bugs without knowing how it works.

Testing

I've arbitrarily chosen split, truncate and whoami as test for my localization system.
Built with no error using cargo build -p uu_split -p uu_truncate -p uu_whoami.
Tested all 3 packages with french locale and it works.
Also tested with LANG=en_US and LANG=zh_CN to check if english works and if the fallback was supported.
Also ran cargo nextest run -p uucore -p uu_split -p uu_truncate -p uu_whoami --no-fail-fast with no fail.

Result

Example with split :

$ uu-split -h (from the AUR)
[only help section]
Usage: split [OPTION]... [ENTRÉE [PRÉFIXE]]

Arguments:
  [input]   [default: -]
  [prefix]  [default: x]

Options:
  -b, --bytes <SIZE>                mettre TAILLE octets par fichier de sortie
  -C, --line-bytes <SIZE>           mettre au maximum TAILLE octets de lignes par fichier de sortie
  -l, --lines <NUMBER>              mettre NOMBRE lignes/enregistrements par fichier de sortie [default: 1000]
  -n, --number <CHUNKS>             générer CHUNKS fichiers de sortie ; voir l'explication ci-dessous
      --additional-suffix <SUFFIX>  SUFFIXE supplémentaire à ajouter aux noms de fichiers de sortie [default: ]
      --filter <COMMAND>            écrire vers la COMMANDE shell ; le nom de fichier est $FILE (Actuellement non implémenté pour Windows)
  -e, --elide-empty-files           ne pas générer de fichiers de sortie vides avec '-n'
  -d                                utiliser des suffixes numériques commençant à 0, pas alphabétiques
      --numeric-suffixes[=<FROM>]   identique à -d, mais permet de définir la valeur de départ
  -x                                utiliser des suffixes hexadécimaux commençant à 0, pas alphabétiques
      --hex-suffixes[=<FROM>]       identique à -x, mais permet de définir la valeur de départ
  -a, --suffix-length <N>           générer des suffixes de longueur N (par défaut 2)
      --verbose                     afficher un diagnostic juste avant l'ouverture de chaque fichier de sortie
  -t, --separator <SEP>             utiliser SEP au lieu de nouvelle ligne comme séparateur d'enregistrement ; '\\0' (zéro) spécifie le caractère
                                    NUL
  -h, --help                        Print help
  -V, --version                     Print version
$ ./target/debug/split -h (built with my changes)
[only help section]
Utilisation: split [OPTION]... [ENTRÉE [PRÉFIXE]]

Arguments:
  [input]    [Défaut: "-"]
  [prefix]   [Défaut: "x"]

Options:
  -b, --bytes <SIZE>                mettre TAILLE octets par fichier de sortie
  -C, --line-bytes <SIZE>           mettre au maximum TAILLE octets de lignes par fichier de sortie
  -l, --lines <NUMBER>              mettre NOMBRE lignes/enregistrements par fichier de sortie [Défaut: "1000"]
  -n, --number <CHUNKS>             générer CHUNKS fichiers de sortie ; voir l'explication ci-dessous
      --additional-suffix <SUFFIX>  SUFFIXE supplémentaire à ajouter aux noms de fichiers de sortie [Défaut: ""]
      --filter <COMMAND>            écrire vers la COMMANDE shell ; le nom de fichier est $FILE (Actuellement non implémenté pour Windows)
  -e, --elide-empty-files           ne pas générer de fichiers de sortie vides avec '-n'
  -d                                utiliser des suffixes numériques commençant à 0, pas alphabétiques
      --numeric-suffixes[=<FROM>]   identique à -d, mais permet de définir la valeur de départ
  -x                                utiliser des suffixes hexadécimaux commençant à 0, pas alphabétiques
      --hex-suffixes[=<FROM>]       identique à -x, mais permet de définir la valeur de départ
  -a, --suffix-length <N>           générer des suffixes de longueur N (par défaut 2)
      --verbose                     afficher un diagnostic juste avant l'ouverture de chaque fichier de sortie
  -t, --separator <SEP>             utiliser SEP au lieu de nouvelle ligne comme séparateur d'enregistrement ; '\\0' (zéro) spécifie le caractère
                                    NUL
  -h, --help                        Afficher les informations d'aide
  -V, --version                     Afficher les informations de version

This function use the preexisting locale id "help-flag-help" and "help-flag-version".
Replace the {{all-args}} with individual section tags.
The title of each section is localized.
They must be checked at runtime or else the titles are unconditionally written.
With the new help template system this function will be unused after updating the packages.
Moreover, "localized_help_template()" was already a replacement.
Support Arg variables with or without a default value.
Only the word "Default" is localized and values are quoted
for readability.
@sylvestre
Copy link
Contributor

is it expected that that many jobs are failing? thanks

@lordeji
Copy link
Author

lordeji commented Nov 23, 2025

@sylvestre The deletion of configure_localized_command() and changing the signature of localized_help_template() is a breaking change for all packages compilation.

My modifications to uucore need to be manually applied to all packages but for now I only updated split, truncate and whoami as a "proof of concept".

If possible, I want to know if my uucore changes are valid before updating every package uu_app() function accordingly with my own changes.
If needed I can update my PR by updating every packages and taking the risk for it to not be accepted.
Don't hesitate to tell me what is the most pratical for you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

l10n: text for --help & --version options is not localized

2 participants