Hi all!
It seems that during the current efforts to modernize the API, the default language (as represented by $wgLang) was changed to always be the content language [1][2] instead of the user language. This may not be a problem for most of the core modules, but broke some essential wikibase API modules (which relied on the actual user language being the default). We propose to change the default behavior back to what it was [3].
I think however that it would be good to first discuss how exactly we WANT the API to behave.
First off, I'd like to point out that there are two distinct use cases for API calls, or rather, two contexts in which API output is shown to a user:
1) Bots. Error messages are shown on the command line. The bot is potentially interacting with multiple wikis at once.
2) UI. The web interface uses the API to implement user interactions. Feedback/error messages are shown to the user directly. In some cases (notably for Wikibase), the language is also relevant for parsing user input and formatting output (think dates, numbers).
The "API help" use case is a bit in between the two, but since it's meant for bot authors, I'd count it under (1); Help shown on Special:ApiSandbox, however, would count under (2).
Now, let's look at the three options we have for the default language in the API:
a) The user language according to user preferences. This used to be the case (technically), it's what wikibase relies on, and it's what [3] reverts to.
b) Hardcoded to "en". This was the de-facto standard for error/help messages, since API messages are/were hard-coded in English.
c) The content language. This is what [1] did.
Option (a) used to be the status quo, and seems intuitive: if I set a default language, I want to use that default language everywhere. API is an integral part of the UI and should behave as such, so it's right for (2).
There is something to be said for option (b) for use case (1): if I run a bot on 100 wikis, I don't want to go and set the user language on all the wikis. Getting error messages in english seems a good compromise (assuming people who can program need to understand at least basic english anyway), and it's what people are used to.
I personally see no advantage in option (c): For use case (1), it means I have to put the uslang parameter in ALL API requests, otherwise I'll see errors in the local language of each of the 100 wikis. For use case (2), it means I get output in the content language instead of my user language - this is just inconsistent, and particularly annoying on multilingual wikis like commons.
The current behavior, option (c), was introduced in the context of localizing the API self-documentation page. If you consider that to be "content", it makes a certain amount of sense, but it breaks a ton of other use cases. Was this even intentional?
I recommend to return to option (a). We can still cover use case (1) by keeping the english message in the current place in the response, and adding the localized message under a different key (and perhaps make it optional). But keep in mind that errors are not the only locale-sensitive output of the API - some API modules generate HTML for display to the user.
What do you think?...
[1] https://gerrit.wikimedia.org/r/#/c/160798/ [2] The goal of the change in question was apparently to support the uselang parameter for API modules, which is a good thing. [3] https://gerrit.wikimedia.org/r/#/c/170895/