I do think that API documentation should be translated, and I can explain why. More than once, people who write user scripts in Hebrew, Russian, or Arabic Wikipedia told me that they are good at JavaScript, but not very good at reading English, so they were happy to see that they can read the documentation in the API sandbox in their own language.
However, by its nature, API documentation will not be read by a lot of people, so it's sensible to say that it shouldn't be the highest priority to translate it. That's why, several years ago, I initiated the separation of the API messages from the general user interface messages in all the extensions, and with some help from other developers, it was completed (see https://phabricator.wikimedia.org/T189982 ). I also put all the API messages in a separate aggregate message group called "Extensions used by Wikimedia - Technical", so that people would be able to translate more "popular" messages in other aggregate groups, like "Extensions used by Wikimedia - Main" and "Extensions used by Wikimedia - Advanced". I totally agree that seeing that there are 4000 (or more) messages to translate is intimidating. That's why I recommend not looking too often at the total number of untranslated messages, but to work extension by extension, and to prioritize things: to translate each extension under "Extensions used by Wikimedia - Main" first, then to go to "Advanced", etc. The "Technical" and "Legacy" groups should be done last, if at all. This should make things more manageable. I wrote a blog post with tips about precisely these things: https://aharoni.wordpress.com/2020/10/23/amir-aharonis-quasi-pro-tips-for-translating-the-software-that-powers-wikipedia-2020-edition/ -- Amir Elisha Aharoni · אָמִיר אֱלִישָׁע אַהֲרוֹנִי http://aharoni.wordpress.com “We're living in pieces, I want to live in peace.” – T. Moore בתאריך יום ה׳, 15 בינו׳ 2026, 09:52, מאת Amir Sarabadani < [email protected]>: > I have a bit more of a radical/spicy idea. Maybe not everything should be > translated? Let me give you an example, Once several years ago I wanted to > finish translation of all Wikimedia deployed extensions to Persian. So I > opened a monstrous 4K list of messages and I struggled to translate almost > all of them (I guess there was a reason no one wanted to translate them). I > vividly remember trying to translate CirrusSearch API documentation to > Persian and it had so much jargon that I had the choice to basically write > a English sentence some Persian words sprinkled in or invent words left and > right (which I'd argue is even worse for the users and defies the point of > the usability). > > I understand that everything in UI should be localized but for API > documentation? I'd argue most devs have decent understanding of English > (even though many can't speak it well, they understand it, there are many > levels to fluency in a language that people who speak one language only > might not know) and worst case, they can use machine translation. Maybe the > API documentation translation can be useful to a very small portion of > people but is it really a good use of our volunteer's time? Isn't it a bit > absurd to enforce a minimum percentage of translation for stuff like API > documentation for an endangered language as a requirement for having a wiki > (policy > <https://meta.wikimedia.org/wiki/Language_proposal_policy#Requisites_for_final_approval> > )? > > Best > > Am Mi., 14. Jan. 2026 um 02:32 Uhr schrieb Travis Briggs < > [email protected]>: > >> As a software developer at an American tech company that develops strings >> for an approximately similar number of languages, I highly support the >> spirit of OP. >> >> I also appreciate Amir's thoughtful and detailed response, as well as the >> others in this thread. However, I think the main takeaway is to ensure that >> developers are actively taking time to be considerate of the string they >> provide, especially in regards to comment strings for translators and >> reduction in complex "special" syntax (though I'm not familiar with the >> technical details or specifics of the MediaWiki system or tw.net). These >> are the guidelines we have in place at work. >> >> Let's strive to educate developers and each other that i18n, l10n and >> a11y (hacker slang for internationalization, localization and >> accessibility) are essential parts of any competent patch, not some >> bureaucratic afterthought that is necessary to get their code published. >> Though I also recognize that this mailing list is probably as good a place >> as any to "get into the weeds". >> >> Cheers, >> -Travis >> >> On Tue, Jan 13, 2026 at 7:54 AM Strainu <[email protected]> wrote: >> >>> Thanks for the responses! >>> >>> În mar., 13 ian. 2026 la 16:37, Amir E. Aharoni < >>> [email protected]> a scris: >>> >>>> >>>> >>>>> It has been a long-standing and documented policy in MediaWiki not to >>>> reuse strings. When developers add the same string several times, they >>>> are, intentionally or unintentionally, following the policy in >>>> https://www.mediawiki.org/wiki/Help:System_message#Avoid_message_re-use >>>> , and it's good that they do. It may seem a bit unintuitive at first >>>> because in computers, repeating yourself is often a bad practice, but in >>>> translatable strings, it's often necessary, because even when the string is >>>> the same in English, it is often different in other languages. >>>> >>>> When the source string and the translation are the same, it usually >>>> doesn't waste the translators' time much because translation memory is >>>> supposed to make a one-click matter. >>>> >>> >>> Except they're not always quite the same, are they? Sometimes you need >>> to click, then adapt the translation, for each of the namespaces in >>> MediaWiki. 10s over 284 languages... >>> >>> >>>> >>>> If you disagree, I'm happy to discuss it further. >>>> >>> >>> There is at least one situation when total deduplication is outright >>> harmful: user controls. I can understand that a "Save" button, a "Save" >>> link and a "Save" page title might be different to provide space for >>> context and customization, but 2 "Save" buttons should not be different. >>> The same, 2 "Log in" links should be the same. It's a matter of semantics >>> and developers are the first to judge this. >>> >>> This is not a theoretical issue: in Romanian, there has been a >>> longstanding debate on whether to use the infinitive or the imperative for >>> buttons. This means that we currently have in tw.net over 12 texts in >>> each form as translations of "Save" (over several projects, of course). >>> This has been somehow improved by clarifying the messages ("Publish" vs. >>> "Save"), but still remains an issue. >>> >>> There are also other parts of the site where consistency should prevail, >>> such as user links (see below), journal entries and probably others. >>> >>> >>>> >>>> >>>>> Another type of duplication are messages 90%+ alike, such as "Talk >>>>>> pages for pages in the main/MediaWiki/.template namespace" instead >>>>>> of "Talk pages for pages in the $1 namespace". I found at least 3 such >>>>>> instances, there might be more. >>>>>> >>>>> >>>> Similarly, the problem with these is that translation of these into >>>> many languages may affect more words and not just that one different word. >>>> Grammar is weird! Theoretically, it could be possible to make some syntax >>>> that chooses the right grammatical form according to the different word, >>>> but it would inevitably complicate the translation syntax and turn >>>> translators into software developers, which is not desirable. Coders should >>>> code, translators should translate. Adding more translation and grammar >>>> syntax would create even more problems of the kind that you describe >>>> further in your email: >>>> >>> >>> I am not really aligned with this. On one hand, we also have strings >>> using the namespace name as a parameter. For the love of consistency, I >>> would prefer to start with a single message everywhere and ask people for a >>> ticket to split a message if needed, not the other way around. On the other >>> hand, the {{int:}} syntax is already used and would solve a lot of the >>> issues I've seen. >>> >>> >>>> >>>>> >>>>>> But wait, there is more. Strings like " [[{{#special:Contributions >>>>>> }}/$1|$2]] ([[{{ns:user_talk}}:$1|talk]]) " should not exist at all. >>>>>> First, there is absolutely no guidance on what parts should be >>>>>> translated. >>>>>> [1] I would guess only "talk", which should be replaced with reusing >>>>>> the simple message (aka {{int:talk}}), so nothing to translate. This >>>>>> would >>>>>> save the translators the significant amount of time needed to decode the >>>>>> message, make assumptions and (not) translate the text. I have some >>>>>> more examples, but I'll stop here. >>>>>> >>>>> >>>> I mostly agree here: there should be as little syntax as possible in >>>> messages. The less wikitext, HTML, magic words, and so on - the better. >>>> PLURAL and GENDER are hard to avoid, and very basic markup like links and >>>> bold font is usually OK, but there should be almost nothing other than >>>> that. Over the years, I did my best to reduce the amount of markup in >>>> messages, and it's still far from perfect. >>>> >>>> This is also a documented policy: >>>> https://www.mediawiki.org/wiki/Help:System_message#Avoid_markup_that_doesn't_need_to_be_translated >>>> >>>> In your specific example, almost everything except the word "talk" >>>> towards the end shouldn't be in the source message, but: >>>> 1. It's probably not a good idea to replace "talk" with {{int:talk}} >>>> because again, in some languages, it can be different in this context. >>>> >>> >>> Specifically in this context, I doubt it should it be different. I mean, >>> I understand Winston's point about parenthesis, but beyond the actual >>> content of the message, I think that references to the users should be >>> standardized throughout the product, regardless of the type of user. It was >>> an unpleasant surprise when the new block interface was deployed and a >>> translated message ended up in romglish: "~2026-12345 (talk) a fost blocat" >>> >>> >>>> 2. The parentheses are often used differently in some languages >>>> (notably, in Chinese), so the translators need to be able to control them, >>>> too. There is a function that inserts language-appropriate parentheses, and >>>> it's used in some places, but in at least some cases, it only complicates >>>> things for both developers and translators, and it would be easier to just >>>> use regular parentheses and let people translate them appropriately. >>>> >>>> The rest of the markup in this message, however, can probably be >>>> reduced or completely eliminated. >>>> >>>> As a translator, I very often file Phab tasks that ask to reduce >>>> complexity of this kind. When it's not too complex, I also make patches >>>> myself. You—and I mean everyone reading this—are welcome to do the same >>>> because I cannot do it all of it perfectly all by myself :) >>>> >>> >>> I'll start doing that myself, thanks for the suggestion. >>> >>> >>>> >>>> >>>>> We must not forget that the translators are also members of our >>>>>> community and the translation time wasted on such strings could be better >>>>>> used doing other activities in the Wikimedia world. The benefits are not >>>>>> small: 1s saved over 284 languages means almost 5 minutes. If fixing your >>>>>> string takes 15 min or less, it's probably worth it. >>>>>> >>>>>> I therefore encourage developers, project and people managers to* >>>>>> review their practices* on generating strings and reviewing code in >>>>>> order to *reduce the number of spurious messages* that the >>>>>> translators need to work on. >>>>>> >>>>> >>>> Even though I disagree with certain technical details in your email >>>> (and I'm happy to discuss them in more detail), I very much agree with its >>>> general spirit! A lot of developers already do it well, but an occasional >>>> reminder doesn't hurt. >>>> >>> >>> Best, >>> Strainu >>> _______________________________________________ >>> Wikitech-l mailing list -- [email protected] >>> To unsubscribe send an email to [email protected] >>> >>> https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/ >> >> _______________________________________________ >> Wikitech-l mailing list -- [email protected] >> To unsubscribe send an email to [email protected] >> >> https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/ > > > > -- > Amir (he/him) > > _______________________________________________ > Wikitech-l mailing list -- [email protected] > To unsubscribe send an email to [email protected] > https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
_______________________________________________ Wikitech-l mailing list -- [email protected] To unsubscribe send an email to [email protected] https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
