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 task. 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
    • Delete the API messages from the original json 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"
      • 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:

If you are working on converting an extension, put your username in the parentheses after its name. Projects marked as (+) are up for grabs, and highly recommended if you're looking for an extension to send a simple patch for because they are among the more commonly translated extensions.

All the extensions that are used by Wikimedia were converted! Thanks to everyone who helped! A checklist for other extensions is being prepared.


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

Details

Related Gerrit Patches:
translatewiki : masterSplit API messages from Math
mediawiki/extensions/Math : masterMove API messages to a separate file
translatewiki : masterSplit API messages from WebAuthn
mediawiki/extensions/WebAuthn : masterMove api help messages to a separate file
translatewiki : masterSplit apihelp messages to a separate file in LiquidThreads
mediawiki/extensions/LiquidThreads : masterMove all apihelp messages to separate files
translatewiki : masterSplit api messages from MachineVision
translatewiki : masterSplit API messages from WikimediaEditorTasks
mediawiki/extensions/WikimediaEditorTasks : masterMove API messages to a separate file
mediawiki/extensions/MachineVision : masterMove api messages to a separate file
mediawiki/extensions/ConfirmEdit : masterMove apihelp messages to a separate file
mediawiki/extensions/DonationInterface : masterMove api messages to a separate file
translatewiki : masterSplit api messages from DonationInterface
translatewiki : masterSplit apihelp messages from Cargo
translatewiki : masterSplit apihelp messages from PropertySuggester
translatewiki : masterSplit apihelp messages from ParsoidBatchAPI
mediawiki/extensions/PropertySuggester : masterSplit apihelp messages to a separate file
mediawiki/extensions/ParsoidBatchAPI : masterSplit apihelp messages to a separate file
translatewiki : masterSplit apihelp messages from PageAssessments
mediawiki/extensions/PageAssessments : masterSplit apihelp messages to a separate file
translatewiki : masterSplit apihelp messages from ProofreadPage
translatewiki : masterSplit apihelp messages from ReadingLists
translatewiki : masterSplit apihelp messages from PageViewInfo
translatewiki : masterSplit apihelp messages from ParserMigration
translatewiki : masterSplit apihelp messages from PageImages
mediawiki/extensions/ProofreadPage : masterSplit apihelp messages to a separate file
mediawiki/extensions/PageViewInfo : masterSplit apihelp messages to a separate file
mediawiki/extensions/PageImages : masterSplit apihelp messages to a separate file
mediawiki/extensions/ParserMigration : masterSplit apihelp messages to a separate file
mediawiki/extensions/ReadingLists : masterSplit apihelp messages to a separate file
translatewiki : masterSplit apihelp messages from SecurePoll
translatewiki : masterSplit apihelp messages from WikibaseQualityConstraints
translatewiki : masterSplit apihelp messages from GettingStarted
translatewiki : masterSplit apihelp messages from JsonConfig
translatewiki : masterSplit apihelp messages from Graph
translatewiki : masterSplit apihelp messages from TextExtracts
translatewiki : masterSplit apihelp messages from ORES
translatewiki : masterSplit apihelp messages from GlobalBlocking
mediawiki/extensions/WikibaseQualityConstraints : masterSplit apihelp messages to a separate file
mediawiki/extensions/Cargo : masterSplit apihelp messages to a separate file
mediawiki/extensions/JsonConfig : masterSplit apihelp messages to a separate file
mediawiki/extensions/SecurePoll : masterSplit apihelp messages to a separate file
mediawiki/extensions/Graph : masterSplit apihelp messages to a separate file
mediawiki/extensions/TextExtracts : masterSplit apihelp messages to a separate file
mediawiki/extensions/ORES : masterSplit apihelp messages to a separate file
mediawiki/extensions/GlobalBlocking : masterSplit apihelp messages to a separate file
mediawiki/extensions/GlobalBlocking : masterMove apihelp translatable messages to separate files
mediawiki/extensions/GettingStarted : masterSplit apihelp messages to a separate file
translatewiki : masterSplit apihelp messages from GeoData
mediawiki/extensions/GeoData : masterSplit apihelp messages to a separate file
mediawiki/extensions/ExtensionDistributor : masterSplit apihelp messages to a separate file
translatewiki : masterSplit apihelp messages from ExtensionDistributor
translatewiki : masterSplit api messages from BounceHandler
mediawiki/extensions/BounceHandler : masterSplit apihelp messages to a separate file
translatewiki : masterSplit api messages from Cite
translatewiki : masterSplit api messages from BetaFeatures
translatewiki : masterSplit api messages from Kartographer and add WV to aggregate group
translatewiki : masterSplit api messages from FeaturedFeeds
mediawiki/extensions/Kartographer : masterSplit apihelp messages to a separate file
mediawiki/extensions/BetaFeatures : masterSplit apihelp messages to a separate file
mediawiki/extensions/Cite : masterSplit apihelp messages to a separate file
mediawiki/extensions/FeaturedFeeds : masterSplit apihelp messages to a separate file
translatewiki : masterSplit api messages from Babel
mediawiki/extensions/Babel : masterSplit apihelp messages to a separate file
translatewiki : masterSplit api messages from CategoryTree
translatewiki : masterSplit api messages from OATHAuth
translatewiki : masterSplit api messages from SiteMatrix
translatewiki : masterSplit api messages from Linter
mediawiki/extensions/Linter : masterSplit apihelp messages to a separate file
mediawiki/extensions/CategoryTree : masterSplit apihelp messages to a separate file
mediawiki/extensions/SiteMatrix : masterSplit apihelp messages to a separate file
mediawiki/extensions/OATHAuth : masterSplit apihelp messages to a separate file
translatewiki : masterSplit api messages from CentralNotice
mediawiki/extensions/CentralNotice : masterSplit apihelp messages to a separate file
translatewiki : master[Newsletter] Split API messages to a separate file
mediawiki/extensions/Newsletter : masterSplit API messages to a separate file
translatewiki : masterSplit api messages from MassMessage
mediawiki/extensions/MassMessage : masterSplit apihelp messages to a separate file
mediawiki/extensions/Babel : masterMove all apihelp translatable messages to separate files
mediawiki/extensions/examples : masterSplit API messages to a separate file
translatewiki : master[AntiSpoof] Split API messages to a separate file
mediawiki/extensions/AntiSpoof : masterSplit API messages to a separate file
translatewiki : masterSplit CentralAuth messages into interface and API groups
mediawiki/extensions/CentralAuth : masterSplit api.* messages to a separate folder
translatewiki : masterGlobalUsage: Split API messages to separated files
mediawiki/extensions/GlobalUsage : masterSplit API messages to a separate file
translatewiki : masterSplit Spam Blacklist API messages
mediawiki/extensions/SpamBlacklist : masterSplit 'apihelp-*' messages into a 'i18n/api/.*' folder
translatewiki : master[GlobalPreferences] Split api messages
mediawiki/extensions/GlobalPreferences : masterSplit api messages to a separate file
mediawiki/extensions/WikibaseLexeme : masterMove api messages to a separate file
translatewiki : masterSplit API messages from Gadgets
mediawiki/extensions/Gadgets : masterMove all apihelp translatable messages to separate files
translatewiki : master[MobileFrontend] Move apihelp messages to a separate file
mediawiki/extensions/MobileFrontend : masterMove apihelp messages to a separate file
translatewiki : masterSplit api messages from JADE
mediawiki/extensions/JADE : masterSplit apihelp messages to a separate file
mediawiki/extensions/UploadWizard : masterMove all apihelp translatable messages to separate files
mediawiki/extensions/UrlShortener : masterMove all apihelp translatable messages to separate files
translatewiki : masterSplit API messages from UploadWizard
translatewiki : masterSplit API messages from UrlShortener
mediawiki/extensions/TemplateData : masterMove all apihelp translatable messages to separate files
translatewiki : masterSplit API messages from TemplateData
mediawiki/extensions/TitleBlacklist : masterMove all apihelp translatable messages to separate files
translatewiki : masterSplit API messages from TitleBlacklist
mediawiki/extensions/CheckUser : masterMove all apihelp translatable messages to separate files
translatewiki : masterSplit API messages from CheckUser
mediawiki/extensions/Scribunto : masterMove all apihelp translatable messages to separate files
translatewiki : masterSplit API messages from Scribunto extension
translatewiki : masterSplit API messages from Thanks extension
mediawiki/extensions/Thanks : masterMove all apihelp translatable messages to separate files
mediawiki/extensions/CirrusSearch : masteri18n: Move apihelp messages to i18n/api
translatewiki : masterSplit API messages from WikiLove #2
translatewiki : masterSplit API messages from WikiLove
mediawiki/extensions/WikiLove : masterMove all apihelp translatable messages to separate files
translatewiki : masterSimplify descriptions of some extensions' aggregate groups
translatewiki : masterMove VisualEditor apihelp/apierror messages to a separate i18n file
mediawiki/extensions/Wikibase : masterSplit Wikibase Client apihelp messages to a separate group
translatewiki : masterMove Wikibase Client apihelp messages to a separate group
translatewiki : masterMove Wikibase Repo apihelp messages to a separate group
translatewiki : masterSplit API messages from Abuse Filter
mediawiki/extensions/Wikibase : masterSplit apihelp messages to a separate group
mediawiki/extensions/AbuseFilter : masterMove all apihelp translatable messages to separate files
mediawiki/extensions/TimedMediaHandler : masterMove all apihelp translatable messages to separate files
translatewiki : masterSplit API messages from Timed Media Handler

Related Objects

Event Timeline

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

Change 532233 had a related patch set uploaded (by Alex Monk; owner: Alex Monk):
[translatewiki@master] Split apihelp messages from PageImages

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

Change 532234 had a related patch set uploaded (by Alex Monk; owner: Alex Monk):
[translatewiki@master] Split apihelp messages from ParserMigration

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

Change 532235 had a related patch set uploaded (by Alex Monk; owner: Alex Monk):
[translatewiki@master] Split apihelp messages from PageViewInfo

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

Change 532236 had a related patch set uploaded (by Alex Monk; owner: Alex Monk):
[translatewiki@master] Split apihelp messages from ReadingLists

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

Change 532237 had a related patch set uploaded (by Alex Monk; owner: Alex Monk):
[translatewiki@master] Split apihelp messages from ProofreadPage

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

Change 532238 had a related patch set uploaded (by Alex Monk; owner: Alex Monk):
[translatewiki@master] Split apihelp messages from ParsoidBatchAPI

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

Change 532239 had a related patch set uploaded (by Alex Monk; owner: Alex Monk):
[translatewiki@master] Split apihelp messages from PropertySuggester

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

Change 532120 merged by jenkins-bot:
[translatewiki@master] Split apihelp messages from Cargo

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

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

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

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

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

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

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

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

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

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

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

Change 532233 merged by Raimond Spekking:
[translatewiki@master] Split apihelp messages from PageImages

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

Change 532234 merged by Raimond Spekking:
[translatewiki@master] Split apihelp messages from ParserMigration

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

Change 532235 merged by Raimond Spekking:
[translatewiki@master] Split apihelp messages from PageViewInfo

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

Change 532236 merged by Raimond Spekking:
[translatewiki@master] Split apihelp messages from ReadingLists

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

Change 532237 merged by Raimond Spekking:
[translatewiki@master] Split apihelp messages from ProofreadPage

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

Krenair updated the task description. (Show Details)Aug 27 2019, 10:57 PM

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

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

Change 532119 merged by Jforrester:
[translatewiki@master] Split apihelp messages from PageAssessments

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

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

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

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

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

Change 532238 merged by Raimond Spekking:
[translatewiki@master] Split apihelp messages from ParsoidBatchAPI

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

Change 532239 merged by Raimond Spekking:
[translatewiki@master] Split apihelp messages from PropertySuggester

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

Lucas_Werkmeister_WMDE updated the task description. (Show Details)

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

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

Amire80 updated the task description. (Show Details)Aug 31 2019, 8:30 PM

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

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

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

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

Amire80 updated the task description. (Show Details)Sep 2 2019, 7:44 AM
ArTrix removed a subscriber: ArTrix.Sep 2 2019, 10:47 AM

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

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

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

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

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

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

Amire80 updated the task description. (Show Details)Sep 3 2019, 8:25 AM
Amire80 added a subscriber: ArTrix.

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

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

Amire80 updated the task description. (Show Details)Sep 3 2019, 8:36 AM

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

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

ArTrix removed a subscriber: ArTrix.Sep 3 2019, 10:04 AM

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

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

Change 534136 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] Split API messages from WikimediaEditorTasks

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

Amire80 updated the task description. (Show Details)Sep 3 2019, 11:31 AM
Amire80 added a subscriber: ArTrix.

Change 534139 had a related patch set uploaded (by Amire80; owner: Amire80):
[mediawiki/extensions/LiquidThreads@master] Move all apihelp messages to separate files

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

Change 534140 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] Split apihelp messages to a separate file in LiquidThreads

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

Amire80 updated the task description. (Show Details)Sep 3 2019, 11:43 AM
ArTrix removed a subscriber: ArTrix.Sep 4 2019, 11:02 AM

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

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

Change 534135 merged by jenkins-bot:
[mediawiki/extensions/WikimediaEditorTasks@master] Move API messages to a separate file

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

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

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

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

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

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

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

Change 534140 merged by jenkins-bot:
[translatewiki@master] Split apihelp messages to a separate file in LiquidThreads

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

Amire80 updated the task description. (Show Details)Sep 5 2019, 7:07 PM
Amire80 added a subscriber: ArTrix.

So! We hit a milestone here \ס/ All the Extensions used by Wikimedia are converted.

Some data:


There are still a few extensions that aren't used by Wikimedia, and that should also be converted this way. Cargo is already converted, and there are some more. I'll make a list soon.

Amire80 updated the task description. (Show Details)Thu, Nov 21, 11:33 AM

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

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

Change 552232 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] Split API messages from Math

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

Amire80 updated the task description. (Show Details)Fri, Nov 22, 9:01 AM

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

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

Change 552473 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] Split API messages from WebAuthn

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

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

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

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

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

Change 552231 merged by jenkins-bot:
[mediawiki/extensions/Math@master] Move API messages to a separate file

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

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

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

Amire80 updated the task description. (Show Details)Tue, Nov 26, 11:45 AM