Open Stack

Excerpts from Ian Y. Choi's message of 2016-11-04 00:58:30 +0900:
> Hello,
> 
> I am from I18n team. Please see inline for my comments.
> 
> Doug Hellmann wrote on 11/3/2016 2:19 AM:
> > Excerpts from Brian Rosmaita's message of 2016-11-02 16:34:45 +0000:
> >> This issue came up during a code review; I've asked around a bit but
> >> haven't been able to find an answer.
> >>
> >> Some of the help output for utility scripts associated with Glance aren't
> >> being translated, so Li Wei put up a patch to fix this [0], but there are
> >> at least two problematic cases.
> >>
> >> Case 1:
> >>      parser.add_option('-S', '--os_auth_strategy', dest="os_auth_strategy",
> >>          metavar="STRATEGY",
> >>          help=_("Authentication strategy (keystone or noauth)."))
> >>
> >> For that one, 'keystone' and 'noauth' are identifiers, so we don't want
> >> them translated.  Would putting single quotes around them like this be
> >> sufficient to indicate they shouldn't be translated?  For example,
> >>
> >>      help=_("Authentication strategy ('keystone' or 'noauth').")
> >>
> >>
> >> Andreas Jaeger mentioned that maybe we could use a "translation comment"
> >> [1].  I guess we'd do something like:
> >>
> >>      # NOTE: do not translate the stuff in single quotes
> >>      help=_("Authentication strategy ('keystone' or 'noauth').")
> > The ability to pass comments to the translators like that seems
> > really useful, if it would work with our tools.
> +1 from me and also Daisy (former i18n PTL).
> 
> I18n team quite agrees what adding translation comments can pass more 
> information to translators from developers.
> 
> > It seems like things we put in quotes should not be translated, by
> > convention.
> I agree with Doug, and Brant's suggestion also looks nice.
> 
> To slightly revise from Brant's suggestion, the following original 
> string for translation looks much better:
> 
>   : "Authentication strategy (%(keystone)s or %(noauth)s).")

Yes, that's the sort of thing I was thinking. Do we need to specify that
the string template use named values like that? Do the names convey
information to the translators?

> 
>   -> %(keystone)s and %(noauth)s will be replaced with "'keystone'" and 
> "'noauth'" correspondingly.
> 
> >
> >> What are other people doing for this?
> >>
> >> Case 2:
> >> We've got a big block of usage text, roughly
> >>
> >>      usage = _("""
> >> %prog <command> [options] [args]
> >>
> >> Commands:
> >>      keyword1    what it does
> >>      keyword2    what it does
> >>      ...
> >>      keyword8    what it does
> >> """)
> >>
> >> We don't want the keywords to be translated, but I'm not sure how to
> >> convey this to the translators.
> > This is a case where using quotes won't work. Using a different
> > tool to build the help text (argparse instead of optparse), or even
> > just building the text from parts inline (put the parts you do or
> > do not want translated into separate variables and then combine the
> > results like a template) might work. Both add a bit of complexity.
> > The second option doesn't require completely rewriting the CLI
> > processing logic.
> I think translators easily capture the context of this kind of command 
> help strings.
> 
> After my brief research on other projects, GNU coreutils also do the 
> same way for extracting translation strings
> (e.g., http://git.savannah.gnu.org/cgit/coreutils.git/tree/src/ls.c#n4882 ).
> 
> For command help strings, translators will prefer not to divide one 
> overall string into multiple line-by-line strings,
> for example:    _("""%prog <command> [options] [args]""") + "\n" + 
> _("""Commands:""") + "\n" + _("""  keyword1  what it does""") .

Yes, I'm sure the original authors would not want to write the text
that way either. :-)

> By the way, can i18n team set any rules within the team,
> for example, "don't translate any words in capital.", "If developers 
> don't want to translate some words, write them in capital.", and so on?

I think in most cases it would be reasonable to assume that words
in all capital letters have special meaning and should not be
translated. Sometimes we can't use that convention, though, because
the input value needs to include lower case values. That is the
situation for the example above, and why I think having notes are going
to be helpful in the long run.

Doug

> 
> What do developers think about this idea?
> 
> 
> With many thanks,
> 
> /Ian
> 
> >> Thanks in advance for your help,
> >> brian
> >>
> >>
> >> [0] https://review.openstack.org/#/c/367795/8
> >> [1] http://babel.pocoo.org/en/latest/messages.html#translator-comments
> >>
> > __________________________________________________________________________
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>