translation

• TranslationMacro, xwiki-platform: the fallbacks, the content parsed as wiki syntax when the key has no translation, else the key itself as plain text.
• ApplicationResources.properties, xwiki-platform: the names and descriptions shown in the Edit Macro dialog, including the untranslated "locale" name.
• XWiki pages of xwiki-platform 18.8.0: about 300 calls, all in application sheets and administration pages, almost all {{translation key="..."/}} , 8 with parameters, 10 with scriptParameters, none with locale or a content.

C1: "The default translation message" does not say when it is shown, when the key has no translation, nor that it is wiki syntax; "default" reads as the message in the default language. The German "Der Standardtext, der angezeigt wird, wenn keine Übersetzung für die gesuchte Sprache gefunden wurde" says it.

C2: optional, which is right: without it, the key itself is displayed.

C4: a text area of the Edit Macro dialog, which fits a short fallback text typed once; the content is not the output of the macro, so it is not expected to be edited in place.

C6: in the Optional parameters tab, before Locale; the most common example sets neither.

C1: "The key associated with the translation" does not say what a key is, the identifier of a text in the translation files or Translations pages of the wiki, like core.menu.create, nor where to find the keys; the macro is in Content, so it is audited as a user macro, see D3.

C2: mandatory with no default, which is right: the key is the text to display.

C4: a plain text field, so the user has to know the exact key, case included: a typo displays the key, see E2. A picker suggesting the keys of the wiki with their text in the current language could be used.

C13: N/A, a key is any text, not a range or a format; the missing picker is counted under C4.

C1: the name "locale" is the parameter ID, shown "Locale" by the dialog, and the description "The locale in which to resolve the translation." uses the developer term locale where the users and the administration say language; it does not say the expected value, like "fr" or "fr_FR". The French "langue" and German "Sprache" use the user term.

C3: the field opens empty, which stands for the current language, the value used in most cases, and the description says it: "Current one is used if not set."

C4: a free text field, although the useful values are the languages of the wiki: an unknown language, like "zz", falls back silently, see E2. A select of the languages, like the one of the Localization administration, could be used.

C8: not marked as advanced, although displaying a text in a fixed language is rare: no XWiki page sets it, only one example of the documentation.

C9: an example of the documentation sets it.

C13: N/A, the value is a language, checked by the select C4 asks for.

C1: "The parameters to pass to the translation" does not say what they are, the values that replace the {0}, {1} placeholders of the translated text, nor that they are separated by commas.

C3: the field opens empty, no parameters, the value used in most cases.

C4: a text field, which fits a list of free values; a field per placeholder of the chosen key would be better but needs the key picker of C4 on key first.

C7: shown with scriptParameters as one feature, the Parameters tab, whose alternatives are selected with radio buttons; neither is required, which is right.

C9: two examples of the documentation set it.

C13: N/A, a list of free texts.

C1, minor: "The name of the script variable containing the parameters to pass to the translation" is accurate for a developer, but does not say that the variable must hold a list, nor that the macro must be written by a user with script right, as the documentation says.

C3: the field opens empty, the value used in most cases.

C4: a text field, which fits the name of a script variable.

C7: shown with parameters as one feature, see parameters.

C8: not marked as advanced, although it only works inside a script macro and needs script right: it is for developers writing sheets.

C9: an example of the documentation sets it, and XWiki sheets use it to pass values computed in Velocity.

C13: N/A, a variable name.