Updating the help text translations is getting harder with each addition

[bitigchi]

Some of the help text in the standart weechat messages is getting too long, and when these texts become fuzzy, it is really hard to figure out what has changed without extensive drilling.

Ideally, each line of the help texts should have its own line in the po files, and the translator can then deal with the lines on an individual basis. This also removes the risk of possible layout issues, newline problems, and such.

Migrating the existing translations might be cumbersome at first, but once everything has been migrated, this will ease the life of the messages' maintainers very easy.

[flashcode]

Yes, I think you speak about help on commands in particular.
I'll check how I can improve this by splitting it into multiple chunks, reuse translations for some lines accross commands.
And I'll check how to do that without having to translate again all commands in all languages…

This might take some time and could be a progressive work.

[bitigchi]

I was also thinking that this would take a great amount of work. Thanks for acknowledging this, it will be a great help to translators!

[flashcode]

I'm starting the work to translate help on command arguments.

Unfortunately, I think this will need a complete re-translation of all commands, this can not be easily retrieved automatically (and I'm going to take this opportunity to simplify help on some commands).

I'll introduce a new format for argument args_description in function hook_command.

Using a special marker at the beginning, the help becomes translated line by line, and there are some automatic formatting (like aligning name of arguments to the right).

For example such existing translation (command /wait):

msgid ""
" number: amount of time to wait (minimum: 1 millisecond)\n"
"   unit: optional, values are:\n"
"           us: microseconds\n"
"           ms: milliseconds\n"
"            s: seconds (default)\n"
"            m: minutes\n"
"            h: hours\n"
"command: command to execute (or text to send to buffer if command does not "
"start with '/')\n"
"\n"
"Note: the command is executed on buffer where /wait was executed (if the "
"buffer does not exist any more, the command is not executed).\n"
"\n"
"Examples:\n"
"  join channel in 10 seconds:\n"
"    /wait 10 /join #test\n"
"  set away in 15 minutes:\n"
"    /wait 15m /away -all I'm away\n"
"  say 'hello' in 2 minutes:\n"
"    /wait 2m hello"
msgstr ""

Would become (one translation per non-empty line, no more newline chars in translations and simplified examples, not translated any more):

msgid "number: amount of time to wait (minimum: 1 millisecond)"
msgstr ""

msgid "unit: optional, values are:"
msgstr ""

msgid ">> us: microseconds"
msgstr ""

msgid ">> ms: milliseconds"
msgstr ""

msgid ">>  s: seconds (default)"
msgstr ""

msgid ">>  m: minutes"
msgstr ""

msgid ">>  h: hours"
msgstr ""

msgid ""
"command: command to execute (or text to send to buffer if command does not "
"start with '/')"
msgstr ""

msgid ""
"Note: the command is executed on buffer where /wait was executed (if the "
"buffer does not exist any more, the command is not executed)."
msgstr ""

msgid "Examples:"
msgstr ""

And the result displayed with /help wait will be almost the same:

[core]  /wait  <number>[<unit>] <command>

schedule a command execution in future

 number: amount of time to wait (minimum: 1 millisecond)
   unit: optional, values are:
           us: microseconds
           ms: milliseconds
            s: seconds (default)
            m: minutes
            h: hours
command: command to execute (or text to send to buffer if command does not start with '/')

Note: the command is executed on buffer where /wait was executed (if the buffer does not exist any more, the command is not executed).

Examples:
  /wait 10 /join #test
  /wait 15m /away -all I'm away
  /wait 2m hello

[flashcode]

There's still something not easy to translate, and that could become harder when you translate line by line: the arguments that are keywords or not.

For example in the /bar command (extract):

hook_command (
    NULL, "bar",
    N_("manage bars"),
    N_("list|listfull|listitems"
       " || add <name> <type>[,<conditions>] <position> <size> <separator> <item1>[,<item2>...]"
       " || default [input|title|status|nicklist]"
       " || rename <name> <new_name>"
       " || del <name>|-all"
       " || set <name> <option> <value>"
       " || hide|show|toggle <name>"
       " || scroll <name> <window> <scroll_value>"),
    N_("         list: list all bars\n"
       "     listfull: list all bars (verbose)\n"
       "    listitems: list all bar items\n"
       "          add: add a new bar\n"
       "         name: name of bar (must be unique)\n"
       "         type:   root: outside windows,\n"
       "               window: inside windows, with optional conditions (see below)\n"
   (...)
);

The following keywords must be kept as-is and then NOT translated:

• list
• listfull
• listitems
• add
• root
• window

But the following arguments must be translated (all words like <this> in the arguments syntax):

• name
• type

Any idea how to make it clear for translators what must be translated or not in description of command arguments?

One possible solution would be to never translate arguments, so keep name and type in English everywhere, and then not even translate the arguments syntax (i.e. the string list|listfull|listitems || add <name> <type>[,<conditions>]...).

[flashcode]

Another solution would be to enclose fixed keywords with backquotes, like this:

      `list`: list all bars
  `listfull`: list all bars (verbose)
 `listitems`: list all bar items
       `add`: add a new bar
        name: name of bar (must be unique)
        type:   `root`: outside windows,
              `window`: inside windows, with optional conditions (see below)

[bitigchi]

I think instead of putting back ticks for the commands, enclosing the arguments in angular brackets would make it easier to distinguish, and provide a 1-1 listing.

I would assume, that any command-line software translator would be aware of the difference between a translatable argument enclosed in angular brackets and an untranslatable command. Rest would be caught during review I think.

Depending on the situation, reusable variable placeholders might also help reducing the confusion.

Also a short l10n comment for such help text would be a nice addition to guide the new folks.

[flashcode]

So this could be:

     list: list all bars
 listfull: list all bars (verbose)
listitems: list all bar items
      add: add a new bar
   <name>: name of bar (must be unique)
   <type>:   `root`: outside windows,
           `window`: inside windows, with optional conditions (see below)

Where:

• <name> and <type> are translated
• root and window are values that can be used, backquotes are welcome there (aren't they?)

Still not sure if it's clear that the first "list" must not be translated while the second one must be in such line, if you don't have the command context:

msgid "list: list all bars"
msgstr ""

(having a translator help on each command argument could be bloated in the gettext file)

[flashcode]

By the way there could be backquotes in translation that are automatically removed on display, eg in French:

msgid "`list`: list all bars"
msgstr "`list`: lister toutes les barres"

displayed as:

      list: lister toutes les barres

[bitigchi]

If the quotes are automatically removed, it should be fine I guess. But it still doesn't tell the translator to leave it as-is. Maybe a comment like:

l10n: only translate the <arguments>, leave the commands as-is

wouldn't be too distracting.

By the way, there is a --no-location flag in gettext that could be run to clean the comments and the other unnecessary info. There are many projects that require this command to be run before submitting the messages file (e.g. vim, git). This only leaves the translations.

[flashcode]

Another proposal: use cmd[xxx] for sub-command names and show that this must not be translated, ie: cmd[list]: ....
This prefix would be automatically removed when help is displayed.

Example of French translation:

msgid "cmd[list]: list all bars"
msgstr "cmd[list] : lister toutes les barres"

msgid "cmd[listfull]: list all bars (verbose)"
msgstr "cmd[listfull] : lister toutes les barres (verbeux)"

msgid "cmd[add]: add a new bar"
msgstr "cmd[add] : ajouter une nouvelle barre"

msgid "name: name of bar (must be unique)"
msgstr "nom : nom de la barre (doit être unique)"

Displayed as this in /help bar:

     list : lister toutes les barres
 listfull : lister toutes les barres (verbeux)
      add : ajouter une nouvelle barre
      nom : nom de la barre (doit être unique)

Would it then be clear that text between cmd[...] must not be translated?

And for the syntax of command, a help text would invite to translate only the text between angle brackets (<name>):

#. TRANSLATORS: only text between angle brackets (eg: "<name>") must be translated
msgid ""
"list|listfull|listitems || add <name> <type>[,<conditions>] <position> "
"<size> <separator> <item1>[,<item2>...] || default [input|title|status|"
"nicklist] || rename <name> <new_name> || del <name>|-all || set <name> "
"<option> <value> || hide|show|toggle <name> || scroll <name> <window> "
"<scroll_value>"
msgstr ""
"list|listfull|listitems || add <nom> <type>[,<conditions>] <position> "
"<taille> <séparateur> <objet1>[,<objet2>...] || default [input|title|status|"
"nicklist] || rename <nom> <nouveau_nom> || del <nom>|-all || set <nom> "
"<option> <valeur> || hide|show|toggle <nom> || scroll <nom> <fenêtre> "
"<valeur_scroll>"

[bitigchi]

Looks good to me!

[weechatter]

I agree. This is better to read and to translate. Especially long help text is very difficult to translate when there are changes in one line only (i'll check the git repository to find out what you changed!).

[flashcode]

Hi,

I merged the changes to translate commands line by line.

The result is that there are now many untranslated or fuzzy strings:

de.po: 2423 translated messages, 222 fuzzy translations, 818 untranslated messages.
pt.po: 1650 translated messages, 752 fuzzy translations, 1061 untranslated messages.
sr.po: 2386 translated messages, 240 fuzzy translations, 837 untranslated messages.
it.po: 1264 translated messages, 956 fuzzy translations, 1243 untranslated messages.
cs.po: 1217 translated messages, 1016 fuzzy translations, 1230 untranslated messages.
pt_BR.po: 869 translated messages, 958 fuzzy translations, 1636 untranslated messages.
es.po: 1299 translated messages, 885 fuzzy translations, 1279 untranslated messages.
ja.po: 1924 translated messages, 572 fuzzy translations, 967 untranslated messages.
hu.po: 77 translated messages, 1590 fuzzy translations, 1796 untranslated messages.
ru.po: 97 translated messages, 1606 fuzzy translations, 1760 untranslated messages.
pl.po: 2224 translated messages, 360 fuzzy translations, 879 untranslated messages.
fr.po: 3463 translated messages.
tr.po: 2216 translated messages, 358 fuzzy translations, 889 untranslated messages.

So the raw keyword is this raw[xxx] and must stay as-is, example of a French translation:

msgid "raw[list]: list all bars"
msgstr "raw[list] : lister toutes les barres"

[flashcode]

Note: there are some changes in translations as well (to reduce the number of translated messages), so you should not always re-use previous translations.

[bitigchi]

Thank you very much @flashcode!

[flashcode]

@bitigchi: you're welcome, I gave you some homework, it's your turn! 😃

[flashcode]

And for your information I'm currently adding back some descriptions for examples in commands: many of them were not relevant, but I removed too many descriptions.

[trygveaa]

This made the help text for eval (/help eval) much less useful. I find it pretty impractical having to go to the Plugin API reference to find all the expression variables and operators. Could that be added back?

[flashcode]

You're right, I'll add this back, with a more readable format (and with new variables added since it was removed).