Page MenuHomePhabricator

Move all apihelp translatable messages to separate files
Open, Needs TriagePublic

Description

I'd like to start this by saying that translatable apihelp messages are great.

Some people think that all people who write software know English, and don't understand why should they be translated at all. This notion is incorrect. I heard from numerous people that they use the API for developing gadgets, and who happily use the translations of Apihelp in Special:ApiSandbox into their language—it's easier for them than to read the API documentation in English. So thanks, @Anomie, for making it possible.

That said, these messages are probably read by fewer people than other user interface messages. Hence, it should be a lower priority to translate them than to translate other messages in core and extensions, which are actually seen by end users who read and edit the wikis. Apihelp messages are useful only to the developers and there are fewer developers than editors.

To actually help translators at translatewiki to do this, Apihelp messages should be separated from other user interface messages. This was already done for core MediaWiki, as well as for several extensions: UniversalLanguageSelector, Translate, ContentTranslation, Echo, Flow, and FlaggedRevisions.

This should be done for all extensions. In particular, this should be done for Wikibase, which has hundreds of apihelp messages, but there are many other extensions that need this.

This requires careful and substantial work, but the process is well-known and there are existing examples. I am therefore marking it as good first bug. This involves:

  • In the extension's Git repository:
    • Under the extension's i18n/ directory, create the api/ directory.
    • In this directory, create en.json and qqq.json files.
    • Find API-related messages. Usually their keys begin with apihelp-*, apierror-*, or apiwarn-*
    • Copy all the API messages from en.json and qqq.json in the i18n/ directory to en.json and qqq.json in the i18n/api/ directory and delete them from the original files.
    • If the extension has extension.json, edit this file and add "i18n/api" to MessagesDirs.
    • If the extension has no extension.json, edit its main PHP initialization file (called ExtensionName.php) and add the api directory to MessagesDirs. See the example from CirrusSearch.
    • If the extension has Gruntfile.js and it has a banana section, then:
      • If you edited extension.json earlier, edit Gruntfile.js in a way that reads MessageDirs from extension.json. See the example from AbuseFilter.
      • If there is no extensions.json, add api: 'i18n/api/' in the banana section.
  • In the translatewiki Git repository:
    • Split the extension configuration in these files:
      • groups/MediaWiki/mediawiki-extensions.txt
      • groups/MediaWiki/ExtensionsAgg.yaml
      • groups/MediaWiki/Wikimedia*Agg.yaml (could be WikimediaMainAgg.yaml, WikimediaAdvancedAgg.yaml, etc.)
    • Notes:
      • The new API group name will be "ext-extensionname-api".
      • The group with the messages for users will be "ext-extensionname-user" or "ext-extensionname-interface".
      • Reuse the extension's description message for the aggregate group's description field. The description message usually has the name "extensionname-desc". For example, for TimedMediaHandler the description value in the YAML file is: description: '{{Special:MyLanguage/MediaWiki:Timedmediahandler-desc/en}}'. Please check that this message actually exists on translatewiki by going to the page MediaWiki://extensionname//-desc/en (example).
      • Create a new aggregate group "ext-extensionname", including the main extension and the API messages using "ext-extensionname-*"
      • Put the API messages group to groups/MediaWiki/WikimediaTechnicalAgg.yaml.
      • Change the entry of the old message group in the aggregate groups files to the new group name. For example, if "ext-scribunto" appeared in WikimediaTechnicalAgg.yaml, the entry must be changed to "ext-scribunto-user".
      • If the previously defined message group has optional or ignored messages and api* messages appear there, move them to the new api group.

Examples:

This is it. Existing translations will be migrated automatically.

See more links to patches in the checklist toward the end of the task description.

The impact for the extensions' developers will be that they'll have to add new apihelp/apierror/apiwarn messages to the i18n/api/en.json and i18n/api/qqq.json files, instead of i18n/en.json and i18n/qqq.json. As far as I can tell, nobody complained about having to do this with Echo, Flow, Translate, etc.

The impact for the translators will be that the cryptic, highly technical, and rarely-seen translatable messages in the "Extensions Used by Wikimedia" group will be separated. As of August 2018, there are more than 1900 such API messages.


Checklist:

This checklist was written semi-manually. It is probably not complete, but it does include some of the larger and more important extensions. Once many of these are done, some more will be added.


A somewhat related task: T167762: Split core en.json to several files.

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

Change 485711 had a related patch set uploaded (by Amire80; owner: Amire80):
[mediawiki/extensions/MobileFrontend@master] Move apihelp messages to a separate file

https://gerrit.wikimedia.org/r/485711

Change 485712 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] [MobileFrontend] Move apihelp messages to a separate file

https://gerrit.wikimedia.org/r/485712

Change 485742 had a related patch set uploaded (by Amire80; owner: Amire80):
[mediawiki/extensions/examples@master] Split API messages to a separate file

https://gerrit.wikimedia.org/r/485742

Amire80 updated the task description. (Show Details)Jan 22 2019, 7:12 AM

Change 485711 merged by jenkins-bot:
[mediawiki/extensions/MobileFrontend@master] Move apihelp messages to a separate file

https://gerrit.wikimedia.org/r/485711

Change 485712 merged by jenkins-bot:
[translatewiki@master] [MobileFrontend] Move apihelp messages to a separate file

https://gerrit.wikimedia.org/r/485712

Change 485904 had a related patch set uploaded (by MarcoAurelio; owner: MarcoAurelio):
[mediawiki/extensions/SpamBlacklist@master] Split 'apihelp-*' messages into a 'i18n/api/.*' folder

https://gerrit.wikimedia.org/r/485904

Change 486267 had a related patch set uploaded (by MarcoAurelio; owner: MarcoAurelio):
[translatewiki@master] Split Spam Blacklist API messages

https://gerrit.wikimedia.org/r/486267

Change 487053 had a related patch set uploaded (by Amire80; owner: Amire80):
[mediawiki/extensions/WikibaseLexeme@master] Move api messages to a separate file

https://gerrit.wikimedia.org/r/487053

Change 485517 merged by jenkins-bot:
[mediawiki/extensions/Gadgets@master] Move all apihelp translatable messages to separate files

https://gerrit.wikimedia.org/r/485517

Change 485518 merged by jenkins-bot:
[translatewiki@master] Split API messages from Gadgets

https://gerrit.wikimedia.org/r/485518

Amire80 updated the task description. (Show Details)Jan 29 2019, 5:19 PM

Change 487053 merged by jenkins-bot:
[mediawiki/extensions/WikibaseLexeme@master] Move api messages to a separate file

https://gerrit.wikimedia.org/r/487053

Amire80 updated the task description. (Show Details)Jan 29 2019, 9:05 PM

Change 487084 had a related patch set uploaded (by Amire80; owner: Amire80):
[mediawiki/extensions/GlobalPreferences@master] Split api messages to a separate file

https://gerrit.wikimedia.org/r/487084

Change 487087 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] [GlobalPreferences] Split api messages

https://gerrit.wikimedia.org/r/487087

Zoranzoki21 updated the task description. (Show Details)Jan 29 2019, 10:32 PM

Change 487093 had a related patch set uploaded (by Zoranzoki21; owner: Zoranzoki21):
[mediawiki/extensions/GlobalUsage@master] Split API messages to a separate file

https://gerrit.wikimedia.org/r/487093

Change 487096 had a related patch set uploaded (by Zoranzoki21; owner: Zoranzoki21):
[translatewiki@master] GlobalUsage: Split API messages to separated files

https://gerrit.wikimedia.org/r/487096

Change 487084 merged by jenkins-bot:
[mediawiki/extensions/GlobalPreferences@master] Split api messages to a separate file

https://gerrit.wikimedia.org/r/487084

Change 487087 merged by jenkins-bot:
[translatewiki@master] [GlobalPreferences] Split api messages

https://gerrit.wikimedia.org/r/487087

Amire80 updated the task description. (Show Details)Jan 31 2019, 12:52 PM

Change 485904 merged by jenkins-bot:
[mediawiki/extensions/SpamBlacklist@master] Split 'apihelp-*' messages into a 'i18n/api/.*' folder

https://gerrit.wikimedia.org/r/485904

Change 486267 merged by jenkins-bot:
[translatewiki@master] Split Spam Blacklist API messages

https://gerrit.wikimedia.org/r/486267

Change 487093 merged by jenkins-bot:
[mediawiki/extensions/GlobalUsage@master] Split API messages to a separate file

https://gerrit.wikimedia.org/r/487093

Change 487096 merged by jenkins-bot:
[translatewiki@master] GlobalUsage: Split API messages to separated files

https://gerrit.wikimedia.org/r/487096

Amire80 updated the task description. (Show Details)Feb 4 2019, 1:06 PM
Amire80 added a subscriber: Jayprakash12345.

Change 488376 had a related patch set uploaded (by Amire80; owner: Amire80):
[mediawiki/extensions/AntiSpoof@master] Split API messages to a separate file

https://gerrit.wikimedia.org/r/488376

Change 488381 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] [AntiSpoof] Split API messages to a separate file

https://gerrit.wikimedia.org/r/488381

Amire80 updated the task description. (Show Details)Feb 6 2019, 12:41 PM
ArTrix added a subscriber: ArTrix.Feb 6 2019, 1:27 PM
Amire80 updated the task description. (Show Details)Feb 8 2019, 3:04 PM
Amire80 updated the task description. (Show Details)Feb 8 2019, 3:21 PM

Change 489484 had a related patch set uploaded (by MarcoAurelio; owner: MarcoAurelio):
[translatewiki@master] Split CentralAuth messages into interface and API groups

https://gerrit.wikimedia.org/r/489484

Change 489481 had a related patch set uploaded (by MarcoAurelio; owner: MarcoAurelio):
[mediawiki/extensions/CentralAuth@master] Split api.* messages to a separate folder

https://gerrit.wikimedia.org/r/489481

Zoranzoki21 updated the task description. (Show Details)Feb 14 2019, 8:12 PM

Change 490923 had a related patch set uploaded (by Zoranzoki21; owner: Zoranzoki21):
[mediawiki/extensions/MassMessage@master] Split apihelp messages to a separate file

https://gerrit.wikimedia.org/r/490923

Change 490925 had a related patch set uploaded (by Zoranzoki21; owner: Zoranzoki21):
[translatewiki@master] Split api messages from MassMessage

https://gerrit.wikimedia.org/r/490925

Zoranzoki21 updated the task description. (Show Details)Feb 15 2019, 8:08 PM

Change 489481 merged by jenkins-bot:
[mediawiki/extensions/CentralAuth@master] Split api.* messages to a separate folder

https://gerrit.wikimedia.org/r/489481

Change 489484 merged by jenkins-bot:
[translatewiki@master] Split CentralAuth messages into interface and API groups

https://gerrit.wikimedia.org/r/489484

Change 488376 merged by jenkins-bot:
[mediawiki/extensions/AntiSpoof@master] Split API messages to a separate file

https://gerrit.wikimedia.org/r/488376

Change 488381 merged by jenkins-bot:
[translatewiki@master] [AntiSpoof] Split API messages to a separate file

https://gerrit.wikimedia.org/r/488381

Amire80 updated the task description. (Show Details)Mar 19 2019, 8:31 PM
Anomie removed a subscriber: Anomie.Mar 20 2019, 1:45 PM

Change 499286 had a related patch set uploaded (by Artrix; owner: Artrix):
[translatewiki@master] [Newsletter] Split API messages to a separate file

https://gerrit.wikimedia.org/r/499286

Change 499292 had a related patch set uploaded (by Artrix; owner: Artrix):
[mediawiki/extensions/Newsletter@master] Split API messages to a separate file

https://gerrit.wikimedia.org/r/499292

ArTrix updated the task description. (Show Details)Mar 26 2019, 6:30 PM
ArTrix added a subscriber: Anomie.
ArTrix removed a subscriber: Anomie.Mar 26 2019, 6:44 PM

Change 485742 merged by jenkins-bot:
[mediawiki/extensions/examples@master] Split API messages to a separate file

https://gerrit.wikimedia.org/r/485742

Change 501557 had a related patch set uploaded (by Nikitrain; owner: Nikitrain):
[mediawiki/extensions/Babel@master] Move all apihelp translatable messages to separate files

https://gerrit.wikimedia.org/r/501557

Change 501557 abandoned by Nikitrain:
Move all apihelp translatable messages to separate files

https://gerrit.wikimedia.org/r/501557

Change 490923 had a related patch set uploaded (by Amire80; owner: Zoranzoki21):
[mediawiki/extensions/MassMessage@master] Split apihelp messages to a separate file

https://gerrit.wikimedia.org/r/490923

Change 490923 merged by jenkins-bot:
[mediawiki/extensions/MassMessage@master] Split apihelp messages to a separate file

https://gerrit.wikimedia.org/r/490923

Change 490925 merged by jenkins-bot:
[translatewiki@master] Split api messages from MassMessage

https://gerrit.wikimedia.org/r/490925

Change 509569 had a related patch set uploaded (by Amire80; owner: Amire80):
[mediawiki/extensions/CategoryTree@master] Split apihelp messages to a separate file

https://gerrit.wikimedia.org/r/509569

Change 509570 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] Split api messages from CategoryTree

https://gerrit.wikimedia.org/r/509570

Amire80 updated the task description. (Show Details)May 11 2019, 8:15 AM
Amire80 added a subscriber: Anomie.

Change 509572 had a related patch set uploaded (by Amire80; owner: Amire80):
[mediawiki/extensions/SiteMatrix@master] Split apihelp messages to a separate file

https://gerrit.wikimedia.org/r/509572

Change 509573 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] Split api messages from SiteMatrix

https://gerrit.wikimedia.org/r/509573

Amire80 updated the task description. (Show Details)May 11 2019, 8:34 AM

Change 509574 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] Split api messages from CategoryTree

https://gerrit.wikimedia.org/r/509574

Change 509575 had a related patch set uploaded (by Amire80; owner: Amire80):
[mediawiki/extensions/CentralNotice@master] Split apihelp messages to a separate file

https://gerrit.wikimedia.org/r/509575

Amire80 updated the task description. (Show Details)May 11 2019, 8:51 AM
Zoranzoki21 updated the task description. (Show Details)May 16 2019, 7:42 PM
Zoranzoki21 added a subscriber: MarcoAurelio.
Zoranzoki21 updated the task description. (Show Details)May 16 2019, 7:46 PM
Zoranzoki21 updated the task description. (Show Details)May 16 2019, 7:49 PM

Change 499292 merged by jenkins-bot:
[mediawiki/extensions/Newsletter@master] Split API messages to a separate file

https://gerrit.wikimedia.org/r/499292

Change 499286 merged by jenkins-bot:
[translatewiki@master] [Newsletter] Split API messages to a separate file

https://gerrit.wikimedia.org/r/499286

Amire80 updated the task description. (Show Details)Sat, Jun 1, 7:18 AM
Amire80 added subscribers: Zoranzoki21, MarcoAurelio.