> > I understand that everything in UI should be localized but for API > documentation?
This is a question we've been asking too. The place we're currently at with the MediaWiki REST API is that our generated OpenAPI specs (which power the REST Sandbox <https://en.wikipedia.org/wiki/Special:RestSandbox>) will include translatable description and summary strings. You can see that many already exist in at least some languages (here's French <https://fr.wikipedia.org/wiki/Sp%C3%A9cial:RestSandbox>, for example). But as we've gone through the actual practice of creating these strings, if I'm being completely honest, it isn't always obvious how to helpfully describe some of the various API parameters even in English, even for endpoints that our team created. Some of the behaviors are very technical and specific, which is sometimes challenging to describe well, even if you're familiar with them. I can only imagine how difficult it is for a translator to understand the context of what these various esoteric things mean. We did mark many of these strings as {{Experimental}} <https://gerrit.wikimedia.org/g/mediawiki/core/+/8c50b22c85d4f59d34709935bea18cd32e877a7f/includes/Rest/i18n/qqq.json>, which hopefully makes this a little friendlier to translators by at least giving them an indication that this might not be the best place to spend a lot of their time. (Thanks again, Amir Aharoni, for creating the {{Experimental}} template!) I'm not sure how that's received on the translator side, though, or how helpful it is in practice. Anyway, our Product Manager, the Technical Documentation team, and various other folks are actively looking at what our best practices should be, and I shouldn't get too far ahead of their efforts. I just wanted to chime in and say that, even though the answers aren't always clear, we're also thinking about how to make the best, most respectful use of translator efforts. Bill Pirkle Staff Software Engineer www.wikimediafoundation.org On Thu, Jan 15, 2026 at 8:51 AM Amir Sarabadani <[email protected]> wrote: > 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/
