Page MenuHomePhabricator

Move all apihelp translatable messages to separate files
Closed, ResolvedPublic

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 extension.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

SubjectRepoBranchLines +/-
translatewikimaster+18 -2
mediawiki/extensions/UserStatusmaster+32 -20
translatewikimaster+16 -1
mediawiki/extensions/ApiFeatureUsagemaster+35 -22
mediawiki/extensions/examplesmaster+0 -8
translatewikimaster+18 -2
mediawiki/extensions/TemplateSandboxmaster+36 -15
translatewikimaster+21 -2
translatewikimaster+25 -3
mediawiki/extensions/Wikispeechmaster+80 -53
mediawiki/extensions/WikispeechSpeechDataCollectormaster+38 -17
mediawiki/extensions/WikibaseMediaInfomaster+36 -16
translatewikimaster+18 -2
translatewikimaster+18 -1
mediawiki/extensions/Mathmaster+28 -11
translatewikimaster+17 -3
mediawiki/extensions/WebAuthnmaster+22 -7
translatewikimaster+17 -2
mediawiki/extensions/LiquidThreadsmaster+186 -136
translatewikimaster+17 -2
translatewikimaster+17 -2
mediawiki/extensions/WikimediaEditorTasksmaster+50 -34
mediawiki/extensions/MachineVisionmaster+66 -49
mediawiki/extensions/ConfirmEditmaster+69 -20
mediawiki/extensions/DonationInterfacemaster+139 -94
translatewikimaster+5 -0
translatewikimaster+17 -1
translatewikimaster+17 -2
translatewikimaster+17 -2
mediawiki/extensions/PropertySuggestermaster+63 -47
mediawiki/extensions/ParsoidBatchAPImaster+48 -33
translatewikimaster+17 -2
mediawiki/extensions/PageAssessmentsmaster+69 -51
translatewikimaster+17 -2
translatewikimaster+17 -2
translatewikimaster+20 -5
translatewikimaster+17 -2
translatewikimaster+17 -2
mediawiki/extensions/ProofreadPagemaster+64 -22
mediawiki/extensions/PageViewInfomaster+60 -42
mediawiki/extensions/PageImagesmaster+38 -24
mediawiki/extensions/ParserMigrationmaster+32 -12
mediawiki/extensions/ReadingListsmaster+171 -152
translatewikimaster+17 -2
translatewikimaster+17 -2
translatewikimaster+17 -2
translatewikimaster+17 -2
translatewikimaster+18 -3
translatewikimaster+18 -3
translatewikimaster+17 -2
translatewikimaster+18 -3
mediawiki/extensions/WikibaseQualityConstraintsmaster+101 -72
mediawiki/extensions/Cargomaster+84 -66
mediawiki/extensions/JsonConfigmaster+62 -38
mediawiki/extensions/SecurePollmaster+65 -33
mediawiki/extensions/Graphmaster+50 -24
mediawiki/extensions/TextExtractsmaster+49 -37
mediawiki/extensions/ORESmaster+131 -44
mediawiki/extensions/GlobalBlockingmaster+88 -47
mediawiki/extensions/GlobalBlockingmaster+86 -42
mediawiki/extensions/GettingStartedmaster+42 -23
translatewikimaster+18 -3
mediawiki/extensions/GeoDatamaster+99 -80
mediawiki/extensions/ExtensionDistributormaster+46 -23
translatewikimaster+17 -2
translatewikimaster+17 -2
mediawiki/extensions/BounceHandlermaster+29 -15
translatewikimaster+18 -3
translatewikimaster+18 -2
translatewikimaster+19 -2
translatewikimaster+18 -2
mediawiki/extensions/Kartographermaster+47 -24
mediawiki/extensions/BetaFeaturesmaster+24 -9
mediawiki/extensions/Citemaster+25 -8
mediawiki/extensions/FeaturedFeedsmaster+30 -15
translatewikimaster+18 -2
mediawiki/extensions/Babelmaster+28 -11
translatewikimaster+18 -2
translatewikimaster+17 -2
translatewikimaster+18 -2
translatewikimaster+18 -2
mediawiki/extensions/Lintermaster+66 -41
mediawiki/extensions/CategoryTreemaster+49 -16
mediawiki/extensions/SiteMatrixmaster+44 -21
mediawiki/extensions/OATHAuthmaster+56 -27
translatewikimaster+18 -2
mediawiki/extensions/CentralNoticemaster+120 -84
translatewikimaster+18 -2
mediawiki/extensions/Newslettermaster+74 -40
translatewikimaster+18 -2
mediawiki/extensions/MassMessagemaster+50 -35
mediawiki/extensions/Babelmaster+20 -9
mediawiki/extensions/examplesmaster+43 -13
translatewikimaster+18 -2
mediawiki/extensions/AntiSpoofmaster+43 -17
translatewikimaster+17 -1
mediawiki/extensions/CentralAuthmaster+169 -148
translatewikimaster+17 -1
mediawiki/extensions/GlobalUsagemaster+31 -16
translatewikimaster+17 -2
mediawiki/extensions/SpamBlacklistmaster+22 -11
translatewikimaster+15 -0
mediawiki/extensions/GlobalPreferencesmaster+77 -58
mediawiki/extensions/WikibaseLexememaster+134 -114
translatewikimaster+15 -1
mediawiki/extensions/Gadgetsmaster+53 -37
translatewikimaster+15 -1
mediawiki/extensions/MobileFrontendmaster+119 -65
translatewikimaster+15 -0
mediawiki/extensions/JADEmaster+47 -29
mediawiki/extensions/UploadWizardmaster+38 -27
mediawiki/extensions/UrlShortenermaster+28 -13
translatewikimaster+16 -1
translatewikimaster+16 -1
mediawiki/extensions/TemplateDatamaster+34 -19
translatewikimaster+16 -1
mediawiki/extensions/TitleBlacklistmaster+32 -19
translatewikimaster+16 -0
mediawiki/extensions/CheckUsermaster+65 -47
translatewikimaster+17 -1
mediawiki/extensions/Scribuntomaster+42 -15
translatewikimaster+16 -1
translatewikimaster+16 -1
mediawiki/extensions/Thanksmaster+51 -26
mediawiki/extensions/CirrusSearchmaster+57 -32
translatewikimaster+11 -0
translatewikimaster+4 -0
mediawiki/extensions/WikiLovemaster+48 -29
translatewikimaster+7 -7
translatewikimaster+10 -1
mediawiki/extensions/Wikibasemaster+116 -70
translatewikimaster+15 -1
translatewikimaster+14 -0
translatewikimaster+17 -2
mediawiki/extensions/Wikibasemaster+669 -587
mediawiki/extensions/AbuseFiltermaster+153 -100
mediawiki/extensions/TimedMediaHandlermaster+58 -44
translatewikimaster+8 -2
Show related patches Customize query in gerrit

Related Objects

Event Timeline

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

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

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

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

Some data:

  • There are now 4187 messages in the "Extensions used by Wikimedia - Technical" group in translatewiki.net. Out of these 4187,
    • 1809 messages of the core API
    • 430 messages in several extensions that are only useful to Ops engineers and Software develoeprs: API Feature Usage, OpenStackManager, and Pool Counter
    • 1948 messages of API messages in the extensions. Some of these are small, but as I wrote in one of the first comments, they add up :)
  • About 65 extensions were converted (although it's possible I missed something). For each extension there was at least one extension patch and one translatewiki configuration patch, and in some extensions follow-up patches. So, there were more than 130 patches here.
  • The big batch towards the end was done by @Krenair using a script that made stuff efficient and mostly automated. Thank you so much!
  • In alphabetical order, @Anomie, @ArTrix, @Jayprakash12345, @Krenair, @MarcoAurelio, @rafidaslam, @Zoranzoki21, and myself submitted patches.
  • In alphabetical order, @abi_, @awight, @brion, @Catrope, @D3r1ck01, @Florian, @Huji, @Jdforrester-WMF, @Jdlrobson, @Krenair, @Krinkle, @Ladsgroup, @Legoktm, @LucasWerkmeister, @MaxSem, @Mholloway, @MSantos, @Nikerabbit, @Raymond, @Reedy, @ssastry, @Tpt, @Urbanecm, and @Yurik helped with reviews. (It's possible I am missing someone here. Sorry!)

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.

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

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

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

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

Change 586301 had a related patch set uploaded (by Amire80; owner: Amire80):
[translatewiki@master] Split API messages from Wikibase Media Info

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

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

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

Change 586301 merged by jenkins-bot:
[translatewiki@master] Split API messages from Wikibase Media Info

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

Change 695256 had a related patch set uploaded (by Amire80; author: Amire80):

[translatewiki@master] Split API files in Wikispeech extensions

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

Change 695257 had a related patch set uploaded (by Amire80; author: Amire80):

[mediawiki/extensions/WikispeechSpeechDataCollector@master] Move all apihelp messages to separate files

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

Change 695258 had a related patch set uploaded (by Amire80; author: Amire80):

[mediawiki/extensions/Wikispeech@master] Move all apihelp messages to separate files

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

Change 695258 merged by jenkins-bot:

[mediawiki/extensions/Wikispeech@master] Move all apihelp messages to separate files

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

Change 695257 merged by jenkins-bot:

[mediawiki/extensions/WikispeechSpeechDataCollector@master] Move all apihelp messages to separate files

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

Change 695256 merged by jenkins-bot:

[translatewiki@master] Split API files in Wikispeech extensions

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

How many extensions are left?

How many extensions are left?

I'm pretty sure I did all the ones that are used by Wikimedia or that are going to be used by Wikimedia in the foreseeable future. I didn't count the others.

How many extensions are left?

I'm pretty sure I did all the ones that are used by Wikimedia or that are going to be used by Wikimedia in the foreseeable future. I didn't count the others.

We are good. https://codesearch.wmcloud.org/things/?q=api&i=nope&files=i18n%2Fen.json&excludeFiles=&repos=

How many extensions are left?

I'm pretty sure I did all the ones that are used by Wikimedia or that are going to be used by Wikimedia in the foreseeable future. I didn't count the others.

We are good. https://codesearch.wmcloud.org/things/?q=api&i=nope&files=i18n%2Fen.json&excludeFiles=&repos=

Thanks! And I should clarify that I didn't do it alone—a lot of people helped!

Change 697081 had a related patch set uploaded (by Amire80; author: Amire80):

[translatewiki@master] Split API files in the Record Wizard extension

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

Change 697149 had a related patch set uploaded (by Amire80; author: Amire80):

[mediawiki/extensions/TemplateSandbox@master] Move all apihelp messages to separate files

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

Change 697150 had a related patch set uploaded (by Amire80; author: Amire80):

[translatewiki@master] Split API files in the Record Wizard extension

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

Change 697166 had a related patch set uploaded (by Amire80; author: Amire80):

[mediawiki/extensions/examples@master] Remove apihelp messages from the main i18n files

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

Change 697081 merged by jenkins-bot:

[translatewiki@master] Split API files in the Record Wizard extension

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

Seb35 added a subscriber: Anomie.

The PR on Github for RecordWizard was merged by @Poslovitch.

Removed Anomie from subscribers -- was added when I edited the description.

Change 697149 merged by jenkins-bot:

[mediawiki/extensions/TemplateSandbox@master] Move all apihelp messages to separate files

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

Change 697150 merged by jenkins-bot:

[translatewiki@master] Split API files in the Template Sandbox extension

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

Change 697166 merged by jenkins-bot:

[mediawiki/extensions/examples@master] Remove apihelp messages from the main i18n files

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

Change 754501 had a related patch set uploaded (by Amire80; author: Amire80):

[translatewiki@master] [Apie Feature Usage] Split apihelp messages to a file

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

Change 754502 had a related patch set uploaded (by Amire80; author: Amire80):

[mediawiki/extensions/ApiFeatureUsage@master] Move apihelp messages to a separate file

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

Change 754502 merged by jenkins-bot:

[mediawiki/extensions/ApiFeatureUsage@master] Move apihelp messages to a separate file

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

Change 754501 merged by jenkins-bot:

[translatewiki@master] [Api Feature Usage] Split apihelp messages to a file

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

Unless I am missing something, all the extensions that are used by Wikimedia have been handled. There are probably some non-Wikimedia extensions still lurking that aren't split, but I guess they can be handled some day. So I'm closing this.

Thanks to everybody for the patches and the reviews!

Nikerabbit claimed this task.
Anomie removed a subscriber: Anomie.

Change 974490 had a related patch set uploaded (by Zoranzoki21; author: Zoranzoki21):

[mediawiki/extensions/UserStatus@master] Move all apihelp translatable messages to separate files + fix failing banana test

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

Change 974492 had a related patch set uploaded (by Zoranzoki21; author: Zoranzoki21):

[translatewiki@master] Split API messages from UserStatus

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

Change 974490 merged by jenkins-bot:

[mediawiki/extensions/UserStatus@master] Move all apihelp translatable messages to separate files + fix failing tests

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

Change 974492 merged by jenkins-bot:

[translatewiki@master] Split API messages from UserStatus

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