Also, current @comment logic does not handle new lines. On one hand, it's a bug, on the other hand, I can use it to insert the documentation I want here.

@shihaohong could you take a look?

I like the idea in concept, but applications that support a larger number of translations would have a massive number of comments. For example, the gallery supports dozens of locales and the comments for each message would be extremely long if we wanted to document every single translation for each message.

To clarify -- Is the issue here difficulty in figuring which translations are missing? There's an option called --untranslated-messages-file that helps list out the messages that are missing translations and for which locales.

Good point. For me the most common case is two supported languages (english + developer's native language), so putting all translations there made sense.

So instead we could put only template language + info for missing translations + maybe some docs about placeholders.

This issue is not really about untranslated messages, I just mentioned it as it seemed nice to have. Actual issue is about having clear information about given localization string without looking up the .arb file or generated code. When writing widgets it's not always clear which text will be used.

BTW, I'm aware of --untranslated-messages-file it's printed every time I'm running the app, but I don't really know which command to use. flutter pub get --untranslated-messages-file x.txt doesn't work.

Actually, that's a bug and has been printing incorrectly. I just submitted #68553 which should fix that issue.

I believe the issue you're facing here is that you're using --untranslated-messages-file correctly, but since you have all translations completed, the file is just not generating. I've made an adjustment in the same PR that causes the tool to generate an empty JSON instead of not doing anything in the event that all messages for every locale have existing translations.

Cool. Then this ticket is mostly about adding some comment docs, could be as simple as:

/// en: Hello there {name}
String helloThere(Object arg0);

I'll take a look into what we can do to make the docs helpful without cluttering it with too much noise. Maybe I'll start with the simple string getters first as a start and iterate to address the more complex ones, like methods with placeholders.

@szotp I created a PR that adds a new comment line with the message value in the template arb locale. Take a look and provide any feedback if you have any!