Details
-
Improvement
-
Resolution: Unresolved
-
Major
-
None
-
17.10.14, 18.8.0
-
None
-
Unknown
-
Description
The description and parameters of the Translation macro use developer terms, like key and locale, without saying what to type, and the macro is in the Content category while it needs developer knowledge.
KOs covered
| Macro | Criterion | Parameters | Problem |
|---|---|---|---|
| translation | D2 summary | "Display a translation message." mostly repeats the name and does not say what the macro adds: the text of a translation key, in the language of the current user, with its parameters filled in. The German description, "Zeigt den übersetzten Text für einen Übersetzungsschlüssel an.", says it. | |
| translation | D3 category | Content, like the compared macro display, but the macro needs developer knowledge, the translation keys of the wiki, which only developers know: the XWiki pages use it in application sheets and administration pages. Development, where developers would also look for it, is missing. | |
| translation | C1 clarity | $content | "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. |
| translation | C1 clarity | key | "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 meant for every user, see D3. |
| translation | C1 clarity | locale | 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. |
| translation | C1 clarity | parameters | "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. |
| translation | C1 clarity | scriptParameters | "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. |
Impact found on macro fluidity
These 7 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, D2 summary, D3 category of its usability criteria. The page of each macro, linked in the table, has the full notes and the steps to reproduce. Fixing them means changing the translations of the macros and, for a name or a category, their definitions.