| Message ID | 20240707153526.97984-2-ash@kambanaria.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | parse-options: localize mark-up of placeholder text in the short help | expand |
Will the patch for expose substitution hint chars be included in 2.46? Should I do anything more? Kind regards: al_shopov На нд, 7.07.2024 г. в 17:35 Alexander Shopov <ash@kambanaria.org> написа: > > i18n: expose substitution hint chars in functions and macros to > translators > > For example (based on builtin/commit.c and shortened): the "--author" > option takes a name. In source this can be represented as: > > OPT_STRING(0, "author", &force_author, N_("author"), N_("override author")), > > When the command is run with "-h" (short help) option (git commit -h), > the above definition is displayed as: > > --[no-]author <author> override author > > Git does not use translated option names so the first part of the > above, "--[no-]author", is given as-is (it is based on the 2nd > argument of OPT_STRING). However the string "author" in the pair of > "<>", and the explanation "override author for commit" may be > translated into user's language. > > The user's language may use a convention to mark a replaceable part of > the command line (called a "placeholder string") differently from > enclosing it inside a pair of "<>", but the implementation in > parse-options.c hardcodes "<%s>". > > Allow translators to specify the presentation of a placeholder string > for their languages by overriding the "<%s>". > > In case the translator's writing system is sufficiently different than > Latin the "<>" characters can be substituted by an empty string thus > effectively skipping them in the output. For example languages with > uppercase versions of characters can use that to deliniate > replaceability. > > Alternatively a translator can decide to use characters that are > visually close to "<>" but are not interpreted by the shell. > > Signed-off-by: Alexander Shopov <ash@kambanaria.org> > --- > parse-options.c | 12 +++++++++--- > 1 file changed, 9 insertions(+), 3 deletions(-) > > diff --git a/parse-options.c b/parse-options.c > index 30b9e68f8a..06d962b00e 100644 > --- a/parse-options.c > +++ b/parse-options.c > @@ -1070,11 +1070,17 @@ static int usage_argh(const struct option *opts, FILE *outfile) > !opts->argh || !!strpbrk(opts->argh, "()<>[]|"); > if (opts->flags & PARSE_OPT_OPTARG) > if (opts->long_name) > - s = literal ? "[=%s]" : "[=<%s>]"; > + s = literal ? "[=%s]" : > + /* TRANSLATORS: change `<>' to other characters or leave as is */ > + _("[=<%s>]"); > else > - s = literal ? "[%s]" : "[<%s>]"; > + s = literal ? "[%s]" : > + /* TRANSLATORS: change `<>' to other characters or leave as is */ > + _("[<%s>]"); > else > - s = literal ? " %s" : " <%s>"; > + s = literal ? " %s" : > + /* TRANSLATORS: change `<>' to other characters or leave as is */ > + _(" <%s>"); > return utf8_fprintf(outfile, s, opts->argh ? _(opts->argh) : _("...")); > } > > -- > 2.45.2 >
Alexander Shopov <ash@kambanaria.org> writes: > Will the patch for expose substitution hint chars be included in 2.46? > Should I do anything more? Sorry, I lost track. Did we resolve why "<>" is special and but "[]" is OK to leave out of the translatable text? IOW, is there much point in advising the translators that "<>" is something specifically they are allowed to change? Stepping back a bit, would translators (especially for languages without any need for the ability to replace <> with something else) understand when told TRANSLATORS: change `<>' to other characters or leave as is why anybody would want to change it in the first place? Stepping back even a bit more, probably making it clear to them what these instances of [<%s>], [=<%s>], etc., are doing would be sufficient to help them making the right decision? If a translator for a hypothetical language that uses say „%s“ reads /* TRANSLATORS: <%s> here stands for an command line argument */ _("<%s>") in the comment, wouldn't that be sufficient to tell them they are allowed to change "<>" to "„“"? Similarly, explaining [<%s>] as "optional command line argument", would tell them that it is OK for them to replace not just <> but also [] if their language requires such a change, no? Thanks for pinging. >> diff --git a/parse-options.c b/parse-options.c >> index 30b9e68f8a..06d962b00e 100644 >> --- a/parse-options.c >> +++ b/parse-options.c >> @@ -1070,11 +1070,17 @@ static int usage_argh(const struct option *opts, FILE *outfile) >> !opts->argh || !!strpbrk(opts->argh, "()<>[]|"); >> if (opts->flags & PARSE_OPT_OPTARG) >> if (opts->long_name) >> - s = literal ? "[=%s]" : "[=<%s>]"; >> + s = literal ? "[=%s]" : >> + /* TRANSLATORS: change `<>' to other characters or leave as is */ >> + _("[=<%s>]"); >> else >> - s = literal ? "[%s]" : "[<%s>]"; >> + s = literal ? "[%s]" : >> + /* TRANSLATORS: change `<>' to other characters or leave as is */ >> + _("[<%s>]"); >> else >> - s = literal ? " %s" : " <%s>"; >> + s = literal ? " %s" : >> + /* TRANSLATORS: change `<>' to other characters or leave as is */ >> + _(" <%s>"); >> return utf8_fprintf(outfile, s, opts->argh ? _(opts->argh) : _("...")); >> } >> >> -- >> 2.45.2 >>
diff --git a/parse-options.c b/parse-options.c index 30b9e68f8a..06d962b00e 100644 --- a/parse-options.c +++ b/parse-options.c @@ -1070,11 +1070,17 @@ static int usage_argh(const struct option *opts, FILE *outfile) !opts->argh || !!strpbrk(opts->argh, "()<>[]|"); if (opts->flags & PARSE_OPT_OPTARG) if (opts->long_name) - s = literal ? "[=%s]" : "[=<%s>]"; + s = literal ? "[=%s]" : + /* TRANSLATORS: change `<>' to other characters or leave as is */ + _("[=<%s>]"); else - s = literal ? "[%s]" : "[<%s>]"; + s = literal ? "[%s]" : + /* TRANSLATORS: change `<>' to other characters or leave as is */ + _("[<%s>]"); else - s = literal ? " %s" : " <%s>"; + s = literal ? " %s" : + /* TRANSLATORS: change `<>' to other characters or leave as is */ + _(" <%s>"); return utf8_fprintf(outfile, s, opts->argh ? _(opts->argh) : _("...")); }
i18n: expose substitution hint chars in functions and macros to translators For example (based on builtin/commit.c and shortened): the "--author" option takes a name. In source this can be represented as: OPT_STRING(0, "author", &force_author, N_("author"), N_("override author")), When the command is run with "-h" (short help) option (git commit -h), the above definition is displayed as: --[no-]author <author> override author Git does not use translated option names so the first part of the above, "--[no-]author", is given as-is (it is based on the 2nd argument of OPT_STRING). However the string "author" in the pair of "<>", and the explanation "override author for commit" may be translated into user's language. The user's language may use a convention to mark a replaceable part of the command line (called a "placeholder string") differently from enclosing it inside a pair of "<>", but the implementation in parse-options.c hardcodes "<%s>". Allow translators to specify the presentation of a placeholder string for their languages by overriding the "<%s>". In case the translator's writing system is sufficiently different than Latin the "<>" characters can be substituted by an empty string thus effectively skipping them in the output. For example languages with uppercase versions of characters can use that to deliniate replaceability. Alternatively a translator can decide to use characters that are visually close to "<>" but are not interpreted by the shell. Signed-off-by: Alexander Shopov <ash@kambanaria.org> --- parse-options.c | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-)