Re: [help-gengetopt] Internationalisation

[Tim Marston]

Hi Lorenzo,

On Mon, Jun 10, 2013 at 07:22:48PM +0200, Lorenzo Bettini wrote:
> I'm quite busy these days, but you can push it to that branch...

Yes, I understand (and sympathise :o).  I'm not expecting any help with
implementing this, and I fully expect to have to update documentation
and the testing framework myself.

I've pushed the changed code to the devel-i18n branch on savannah:

  http://git.savannah.gnu.org/cgit/gengetopt.git/log/?h=devel-i18n

> can you summarize the changes, please?

Here's a summary of what I've been doing...

- A new string_builder class is used to dynamically allocate and
  generate strings at runtime that may consist of mixed un-localised,
  application-localised and gengetopt-localised parts.  Where parts of
  the generated string are application-localised, they can also include
  notes for translators.

- The three generated help string arrays -- args_info_usage,
  args_info_purpose, args_info_versiontext and args_info_description --
  are now always initialised dynamically from a static function,
  init_strings(), called from init_args_info(), and never with static
  strings.

- String wrapping is now done at runtime, in the generated code, since
  strings only get localised at runtime.  Also, the alignment position
  for option descriptions is now calculated at runtime, since parts of
  the description of options (e.g., type names) may be localised.
  Wrapping and alignment is done on characters, not bytes.

- In generated code, the three help string arrays --
  gengetopt_args_info_help, gengetopt_args_detailed_help and
  gengetopt_args_full_help -- are now generated in groups of three.
  The three elements are wrapped differently, and are referred to
  internally as "header" (text to be alligned at column 0), "text"
  (text to be alligned after a small indent, at column 2) and "extra"
  (text to be aligned at the column position for option descriptions,
  determined at runtime).

- The three help string arrays are no longer declared extern as their
  internal representation has changed significantly and silently being
  compatible with existing software that uses them would produce
  undesired results.

- gengetopt_args_info_usage, gengetopt_args_info_purpose and
  gengetopt_args_info_description are no longer declared extern, as
  they are generated dynamically and silently being compatible with
  existing software may produce undesirable results (quite possibly
  segfaults).

- args_info::<option>_help has been split in to <option>_help_param and
  <option>_help_desc since the parameter and descriptions strings are
  now separate, internally.  The change in name intentionally breaks
  compatibility (since the strings are different).

- Code that handles --show-help (et al.) has been rewritten (to use the
  new OptionHelpListElements and string_buidler data structures).

- A "po-client" directory has been added to the project for translation
  of strings in the "gengetopt-client" message domain.  This is for use
  by generated code in client programs; it is not internationalisation
  of gengetopt, its self (which could someday be done in the usual "po"
  directory).

- Strings in generated code have been modified for i18n, (as per
  http://www.gnu.org/software/gettext/manual/gettext.html#Preparing-Strings)
  and notes for translators added, where appropriate.

- In generated code, added macros _(), GENGETOPT_() and GENGETOPT_N()
  (for resolution of strings that need to consider plurality), added an
  initialisation function that binds the gengetopt's client message
  domain to the directory used at gengetopt configure-time.

There are some known limitations...

- The "simulated" output produced by --show-help (et al.) currently
  doesn't undergo localisation, as this would require knowing the
  message domain of the client program.  If this is an issue, perhaps
  we could provide another command line option to specify the client
  message domain.

- Prior to the changes, the generated (client) code assumed it could
  output in US-ASCII.  It now assumes it can output in UTF-8.  I'm
  unsure as to how unreasonable this assumption is.  I think the
  "proper" solution, though, would be to convert all output of the
  generated code to the current character encoding on the fly.

I also have some more stuff to do before I'm finished...

- Gengetopt's "inserted" help string descriptions (such as "Print help
  and exit") are currently localised in the client message domain, not
  gengetopt's client message domain.

- The --show-required option's STRING parameter is currently always
  localised in the client message domain.  This is OK when it is
  specified, but not when it defaults to "(mandatory)".

- Documentation will need to be updated.

- The testing framework needs to be updated/checked.

I'll be working on that last stuff over the coming weeks, but I just
wanted to check in with you, since I'm coming to the end of adding
internationalisation, and show you what I've been doing.

What are your thoughts?  Do you approve of the changes?

-- 
Tim Marston
ed.am