Translatable modules/Principles/en

 These are the principles according to which the Translatable modules framework will be designed, implemented, and deployed.

Translation experience must be similar to that of core, extensions, and pages
The translators’ user experience must be similar to the experience of translating core MediaWiki and extensions on translatewiki.net, and to translating pages on meta, mediawiki.org, and so on. However, necessary adjustments will have to be made.

All multilingual wikis
At this stage, the project must address the needs of all multilingual Wikimedia wikis: Wikidata, Commons, Meta, mediawiki.org, and possibly also Outreach, Incubator, Multi-Wikisource, Beta Wikiversity, Wikimania, Wikispecies. All wikis that have the Translate extension are potential targets. (All Wikimedia content wikis run Scribunto.)

It should also be useful for any wiki project outside of the Wikimedia world that uses Scribunto modules.

Transition goal
Once the framework is developed and deployed, module developers should feel encouraged and empowered to create new modules that have translatable messages using the new framework, and to convert existing modules to this framework.

To make transition to the new framework easier for Module and template developers, it may be good to develop scripts that convert source strings and translations from existing translated modules to the new framework.

Standardization
The same framework should be deployed and used on all of Wikimedia’s multilingual sites. All the Scribunto functions to load and parse messages will be added to extension code and deployed everywhere. No local modules should be needed to use the framework.

Wiki principles
The source messages must be easily editable by wiki editors, much like modules and templates are now. Most of them must be editable by all editors. Some of them may be protected from vandalism to be editable only by people in particular permission groups, such as “interface editors” or “sysops”, according to wiki community policies.

It must be reasonably easy to find who contributed a translation using page history, logs, or some other mechanism.

Finding messages to translate
There needs to be an easy to browse catalog of modules whose messages need to be translated. This is similar to the main page in translatewiki.net. The primary entry point to this must be Translate’s Message group selector. The grouping must be controlled by the wiki editing community. The grouping is needed because a wiki may have hundreds or even thousands of translatable modules, and looking them up in one message group selector is not scalable.

It should also be convenient to find messages to translate from the modules’ documentation pages and from the pages that invoke them, and to use ?uselang=qqx in the URL to find message keys.

It should be possible to mark some messages as “optional”, as it is done for MediaWiki messages in translatewiki.net.

Performance and updating
The new framework must not significantly hurt the wikis’ performance. It must not add page save, load, or rendering cost.

Once a source message is updated, it must be immediately seen on the pages where the module is used, similarly to how pages that use templates and modules are re-rendered after the template or the module is updated. The existing translations must appear as out of date (“fuzzy”) in the translation interface, and should appear with an indication that they are out of date in the rendered wiki page where the module is invoked.

Editing raw messages
The source messages will be edited in the storage that will be selected: a wiki page with JSON, a translatable wikitext page, or something else (to be decided). Source messages should have context documentation, similarly to “qqq” in core MediaWiki and extensions, and they will be edited raw, or through Translate’s “Edit documentation” feature.

Editing the translations as raw source code is not supposed to be necessary. Translations should be edited only through a translation interface. In core and extensions it’s essentially the only way to edit translation, although it may be possible to allow editing translations manually if there is strong community demand for it.

Local customization of messages
Wikis must be able to change translations that come from another wiki, as it is with core and extensions messages, which can be customized in the MediaWiki namespace. This is not immediately relevant for single wikis (unless we store the translations for all sites on Commons), but it will definitely become relevant when modules start being global.

Message syntax and parameters
In core MediaWiki and extensions, many messages have parameters, sometimes also known as “placeholders”. They are named $1, $2, etc., and they are filled in run time. Parameters are particularly important for making messages robustly translatable because different languages have different word order. Something like this is needed in modules, too.

The magic words PLURAL, GENDER, and GRAMMAR will be supported in module messages as in MediaWiki messages. This should be available for both content language and page language.

Translation memory
The Translate interface must use Translation memory as it does with translatable pages and MediaWiki translation.

Sharing messages across modules
It is an open question whether to allow the sharing of the same message or several messages across several modules. It is usually discouraged in MediaWiki (Avoid message re-use), however, it is conceivable that this will be useful for module developers.

To be decided later, in the community consultation stage.

Importing and exporting
Messages must be easily and automatically importable and exportable by Special:Import and Special:Export. This is similar to TemplateStyles: If a template uses TemplateStyles, the Import function automatically imports the necessary CSS pages in the same XML package.

More information

 * Discuss at Talk:Translatable modules.
 * - the part that needs the most discussion and review
 * - the part that needs the most discussion and review
 * - the part that needs the most discussion and review