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.

This task covers only translation of descriptions of response body properties. Other tasks cover translation of descriptions of path/query parameters and request body parameters.

• 1. Conditions of acceptance
• Follow the "rest-property-desc-revision-id" example (see link below) to replicate the translation behavior for all response body properties across schemas for 'content.v1' endpoints:
• NewPage.json
• ExistingPageBare.json
• ExistingPageSource.json
• ExistingPageHtml.json
• RevisionMetaDataBare.json
• RevisionMetaDataWithSource.json
• ExistingRevisionHtml.json

• In cases where there are shared parameters (eg: same string used in multiple schemas), create a single translation string that can be used in all places.
• Additional schemas not in content.v1 will be covered under one or more separate tasks.

Implementation details

Example: https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1093936/12/includes/Rest/Handler/Schema/RevisionMetaData.json#17 -- see "rest-property-desc-revision-id" in RevisionMetaData.json as reference example.

1. the endpoint developer replaces the existing "description" key/value with the "x-i18n-description" key, with the message key as the valuye. You can see an example here.
2. the endpoint developer then defines an associated qqq entry and en entry. 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 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.

Note: some English strings may already be available from the documentation on the API Portal. For those cases, those strings should be used.