[gen_l10n] Exposing tool's options when using l10n.yaml to configure

[shihaohong]

When running gen_l10n from the command line, there are descriptions for each option that are available to the user. When using l10n.yaml to configure and use the gen_l10n tool, we should still have a good way to share the list of available options with users, as well as descriptions for how to use the tool.

[christopherfujino]

which command line tool?

[shihaohong]

Sorry, I just clarified in the original comment! I mean when running the gen_l10n tool from the command line

[shihaohong]

One solution that @HansMuller and I have been discussing would be to have flutter create generate an empty l10n.yaml file in new Flutter applications with comments that describe what each option does. In that case, we'd need the flutter tool to not run the gen_l10n tool when there's an empty l10n.yaml file.

I'd like to solicit alternative solutions as well, but the idea is that we need some way for users to know how to configure the l10n tool that is discoverable. The flaw to the solution presented above is that someone would have to run flutter create to even realize that gen_l10n is configurable thought l10n.yaml, which seems like a problem if you want to use the tool for existing Flutter applications. Another problem would be that these comments could get outdated as the tool itself changes (new options, modifications to existing options).

We (Hans and I) are already in the process of writing a user guide for the tool, but that runs the risk of being outdated too (which is probably fine, any user guide or tutorial runs into this problem).

@jonahwilliams Is there a way to surface the updated list of the gen_l10n tool's help text that is more discoverable through the Flutter tool? Currently, we can bring up the help text by running dart ${FLUTTER_PATH}/dev/tools/localization/bin/gen_l10n.dart --help.

[jonahwilliams]

flutter create is intentionally very minimal. It doesn't include a lot of other feature like assets, desktop layout, dark mode, et cetera. I'm not sure if localization fits. @Hixie as the keeper of the template

I would also not expect that exposing the options through the tool commands to be very discoverable, given that the majority of our users run the tool via IDEs. Perhaps we could add some sort setup localizations command to the tool and work with the IDE teams to expose it ( @devoncarew @DanTup ).

Do we always require at least one arb file for localizations, or can it handle having no inputs? Otherwise adding an l10n.yaml file might break a project.

Have you started on a longer form document on how to use l10n.yaml? Publishing something like that one the website and linking from https://flutter.dev/docs/development/accessibility-and-localization/internationalization seems like the best approach. FYI @sfshaza2

[DanTup]

Perhaps we could add some sort setup localizations command to the tool and work with the IDE teams to expose it ( @devoncarew @DanTup ).

We already have a few VS Code commands that just wrap simple shell commands (for ex. flutter doctor and flutter pub outdated), so we could easily do the same to expose it there if it makes sense. Is it just a fixed command, or does it require the user to provide arguments/options?

[shihaohong]

@jonahwilliams We require at least one arb file for localizations. A user guide has been started already and it includes a section on how to fill out l10n.yaml, so that would probably be a good start.

@DanTup The command requires the user to provide arguments/options. All the options and their descriptions are defined here.

[jonahwilliams]

@shihaohong we could generate a blank/empty arb file or one with a trival message. Then include l10n.yaml with all options documented and commented out.

[DanTup]

We can take inputs from the user, but we can't show dialogs in VS Code so it'd end up being one-step-per-option. It would also mean we'd have to code those options into the editor extension (which may complicate changing them).

Is it feasible to come up with defaults for all of the required options? That would keep the command simple for most people and if they need to deviate they can run the command themselves through the embedded terminal?

[jonahwilliams]

In this case, the user would not provide these options via the command line, but with a l10n.yaml file in their project directory. This tool command could generate this file with the options commented out with example values.

[sowens-csd]

Any updates on this? I'm looking for a description of the options available in the l10n.yaml file and haven't found it yet. The link provided above is a 404. In particular I'd like to specify the name of the generate localization class in place of AppLocalizations.

Just after posting this I found out how to change the generated class name. I found that here https://github.com/flutter/gallery/blob/master/l10n.yaml.

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: my_app_localizations.dart
output-class: MyAppLocalizations

[shihaohong]

The list of options are here. You can also get the list of options by running flutter gen-l10n --help.

[sowens-csd]

Thanks!