ArgGroup: localization of heading text

[deining]

Some more feedback on picocli 4.0.0-alpha-1, as invited / requested in the release::

I defined a mutually exclusive argument group and specified a heading for the group and description for the option(s). This worked fine.
In the next step, I wanted to put these string resources (heading, description) into a resource bundle.

First, I had a look at chapter 16. Internationalization of the manual, but I couldn't find anything related there (maybe you can extend the documentation here!?). Later on, I found the following description in the manual:

7.3. Option Sections in Usage Help

The example below uses groups to define options sections in the usage help.
When a group has a non-null heading (or headingKey), the options in the group
are given the specified heading in the usage help message. The headingKey
attribute can be used to get the heading text from the command’s resource bundle.

I played around quite a while, but I couldn't get it working.
My code looks like:

    @Command(subcommands = { TestSubCommand.class, CommandLine.HelpCommand.class }, name = "ArgGroupsTest", resourceBundle = "test.Bundle")
    static class TestCommand implements Runnable {

        @Option(names = "-q", required = true)
        static boolean quiet;
        
        @ArgGroup(exclusive = true, multiplicity = "1", headingKey = "myKey" )
        DataSource datasource;

        static class DataSource {
            @Option(names = "-a", required = true)
            static boolean isA;
            @Option(names = "-b", required = true)
            static File dataFile;
        }

Bundle.properties

ArgGroupsTest.quiet= My description for option quiet  # this works
ArgGroupsTest.a= My description for exclusive option a  # this works, too
ArgGroupsTest.datasource.myKey = My heading text   # incorrect, doesn't work, don't know why

Can you advice what me what keys need to be used here?

In the release notes, you asked:

Is the documentation clear and complete?

IMHO, chapter 16. Internationalization is a bit sparse. Having dealt with i18n issues some time ago, I read the chapter again today and things came back to my mind. For me i18n was quite a challenging task, I'm on the impression that documentation could and should be a bit more elaborate here.

Example:

16.2. Example Resource Bundle, after the first code block:

For options and positional parameters, the descriptionKey can be used
to localize the description.

It might be unclear what descriptionKey means here. It would already help to write:

For options and positional parameters, the optional annotation attribute `descriptionKey`
can be used to localize the description.

It would be even better to have a full working example here. Maybe we can add an example to the codebase and link to it from the manual, preventing the manual from getting bloated.

Another example:

...
# Option Descriptions
# -------------------
# Use numbered keys to create multi-line descriptions.
help = Show this help message and exit.
version = Print version information and exit.

Again, description is quite terse, I would prefer to have a more verbose version here, something like

# Option Descriptions
# -------------------
# Use numbered keys to create multi-line descriptions.
#  user defined options
optionA = using this custom option, you may ...
optionB = this option declared , you may ...
#  mixin standard help options
help = Show this help message and exit.
version = Print version information and exit.

Just my ideas, thanks for your continued great work on picocli!

[remkop]

That's great feedback, thank you!

About your first question, the resource bundle keys can be prefixed with the command name but not with arg group names. For the purpose of localization, the arg groups are ignored; keys are just the option names with optionally the command name as prefix. Since options need to be unique in the command, this should not be a problem. Definitely need to improve the docs though!

ArgGroupsTest.quiet= My description for option quiet  # this works
ArgGroupsTest.a= My description for exclusive option a  # this works, too
ArgGroupsTest.datasource.myKey = My heading text   # incorrect, doesn't work, don't know why

The above is the expected behaviour.

I like all your suggestions to improve the docs, in addition we can also add an example to picocli-examples/src/main/java/picocli/examples/arggroup.

Do you feel like providing a pull request for this?

[deining]

Thanks for your quick reply.

I'm still struggling with the localization of the heading of an argument group. Using a literal string as heading text (using the code fragment given below) works great for me:

@ArgGroup( exclusive = true, multiplicity = "1", heading = "My custom heading" )
DataSource datasource;

It's still unclear to me, however how to put the heading string in a resource bundle. I tried this, to no avail:

@ArgGroup( exclusive = true, multiplicity = "1", headingKey = "myBundleKey")
DataSource datasource;

Bundle.properties:

ArgGroupsTest.myBundleKey = My localized heading text   # doesn't work, please advise what's wrong here

Hopefully you can clarify what's the correct way to get the heading text of an argument group localized.

I like all your suggestions to improve the docs, in addition we can also add an example to picocli-examples/src/main/java/picocli/examples/arggroup.

Great to hear that.

Do you feel like providing a pull request for this?

Yes, I will try to prepare a PR. I can't promise it though.

[remkop]

My bad. Looking closer I just realized that localization of heading text has not been implemented yet...
I'll try to push a fix to master as soon as possible.

[remkop]

I pushed a fix with unit test for the broken arg group heading localization to master. It should work now. Please verify.

Note that the heading text should end with %n or the option will be on the same line.
This is to be consistent with other section headings in the usage help.

[deining]

Please verify.

I can confirm that it works now as expected. Thanks for your great work!

[remkop]

Added more detailed examples to the Internationalization section in the user manual, as discussed above.
Let me know if you find additional points for improvement!