Description

MediaWiki benefits from pre-established patterns for enabling content translation. We need to surface the strings to our translator community, so that we can use them as part of our automated OpenAPI spec generation.

• 1. Conditions of acceptance
• Follow the "rest-param-desc-revision-id" example (see link below) to replicate the translation behavior for all request parameters across 'page' endpoints as part of the 'getParamSettings()' call:
  • POST: w/rest.php/v1/page
  • GET: w/rest.php/v1/page/{title}
  • PUT: w/rest.php/v1/page/{title}
• In cases where there are shared parameters (eg: POST and PUT both require 'source' and 'comments'), create a single translation string that can be used in both places.
• Additional endpoints will be covered in subsequent tickets.

Implementation details

Example: https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1078506 -- see "rest-param-desc-revision-id" as reference example.

1. the endpoint developer inserts the translation keys (like, literally types them in) when creating the endpoint. You can see an example here. Very simple, the hardest part is figuring out what to call it.
2. the endpoint developer then defines an associated qqq entry and en entry. Also very simple, with the caveat that the en version does get shown to end users who view the API spec, so you want that string to be suitable for that purpose.
   1. the real magic happens, where human translators on translatewiki create the translations into all the other languages
3. the translatewiki system adds the translated strings to the various other languages. You can see here that, for my example, it is now available in a bunch of languages. More will appear over time as translators on translatewiki see strings in need of translation and create translations into languages they know. As an endpoint developer, I don't have to do anything at all when new translations come in. They just work. Thing of beauty.
4. at runtime, when the OpenAPI spec is requested and generated on the fly, our internationalization code in MediaWiki looks up the appropriate translation and substitutes in that string. If no translation is available, English is used as a fallback, and we know English is always available because the endpoint developer typed it in during step #2.