Global templates/Transition

The implementation of Global templates and modules has two sides:


 * 1) The creation of the repository and the infrastructure that makes it possible
 * 2) The work by editors of multiple wiki projects to move the existing templates to this repository.

The “” document primarily addresses the infrastructure. (Also, as of June 2020, it mostly speaks about it on the level of product requirements and not on the level of internal technical architecture.)

This document here tries to address the other side: How will editors of wiki projects use this infrastructure once it’s available. It may seem that writing such a document so early in the process is too far-fetched because doing any of these things will be possible only when the infrastructure is actually deployed. However, it is useful to try to think about it as early as possible because it can inform the development of the technical infrastructure and the planning of its implementation. It may also help the developers understand which parts of this process can be at least partly automated. Once the infrastructure exists, this page will be converted from a theoretical plan to a practical transition guide.

As with all the other documents about Global templates, this is not the work of one person or a small group. The comments of all editors, developers, and other stakeholders are welcome—otherwise it just won’t work.

What happens today
So, let’s say that you want to write an article in the Wikipedia in your language about the city of Shanghai, and you want to have in it an infobox like the one in the English Wikipedia article about it. You figure out that you have to type, but when you publish, you see a red link: Template:Infobox settlement. So you figure out that you probably have to copy the whole template to your wiki.

If you don’t know much about programming and wikitext (also known as wiki syntax), then you have these options:


 * 1) Make a simpler template with fewer features.
 * 2) Make a table that looks kind of like the infobox. (And then make such a table in every article about every city.)
 * 3) Just give up and have an article about Shanghai without an infobox.

If you do have some time and some knowledge about programming and wikitext, then here’s a simplified list of what you’ll have to do:


 * 1) Copy the code of this template to your wiki. As of this writing, it’s 57,071 bytes and 940 lines.
 * 2) Realize that this template actually uses a lot of other templates. Learn how to use Export feature. Export the template, with the  option enabled. As of this writing, this will import 130 templates and modules, and the XML dump will have more than 40,000 lines.
 * 3) Go through all the wiki syntax code you copied, find all the human-readable user interface strings that have to be translated, and translate them. Be careful not to touch parameters and parser functions.
 * 4) Go through all the wiki syntax and Lua code that you copied in 130 templates and modules, find all the parameter names and where they are used, and change them to your language. (This step is optional, but useful for editors who don’t know English.)
 * 5) Change the parameter names in TemplateData, but keep the English names as aliases.
 * 6) Copy the documentation pages, delete all the English text from them, and write the same text in your language. Be careful to change the parameter names.
 * 7) Check that the template actually works and does what you need. If it does not, you may have to search for CSS or JS pages on which it depends.

(This doesn’t apply to the current version of, but on many other templates you’ll also have to copy the TemplateStyles. This will be done automatically by the export tool, but you’ll have to verify that it actually worked.)

You have to do all of this for every template that doesn’t exist in your wiki. And it has to be done in every wiki. That’s basically the problem that the Global templates proposal is trying to solve.

Working together
A cross-wiki community of template and module maintainers will have to arise as early as possible. It must be truly global, serving all projects equally: Wikipedia, Wikidata, Commons, and even the less famous projects, such as Wikinews and Wikispecies. All wikis need global templates and there must be no preferential treatment.

TODO: Add some more details about cross-wiki community building...

What to migrate
It was discussed several times what templates and modules should be migrated, for example on the pages meta:Which templates should be global? and Multilingual Templates and Modules. All the proposals there make sense.

One approach may be to define which are the most used modules and templates across versions and projects, and then start the migration from there. Attention: the keyword here is used, not needed, since this will help us on two different levels:
 * 1) Focusing on what is already a core functionality across projects; and
 * 2) Demonstrating that the whole project works and has positive feedback for involved communities.

Potential candidates for this “phase 1 migration” might be:


 * Module:Arguments, used on ~340 projects
 * Module:String, used on ~285 projects
 * Module:No globals, used on ~275 projects
 * Module:Wikidata, used on ~140 projects
 * Template:Ambox, used on ~350 projects
 * Template:Speedy delete, used on 820 projects
 * Template:Bot, used on 654 projects
 * All the modules managed by the bot, because they are already global in practice.
 * The various Cite templates and modules

And so on. A more precise list of potential candidates can be this one. (It should be noted how many “universally needed” modules and templates are not present in all projects, one more time underlining the necessity of such a project)

What should be avoided, though, it’s a potential feeling of imposing something to the community. This can arise when locally a module or a template has been modified to the point that it’s not similar to the one of other communities. For this reason, phase 1 should probably limit to “non-controversial modules and templates”, i.e. modules and templates with the most basic functionalities as possible—speedy deletions, boxes, and such.

Migrating modules
''TODO: This is only an outline. The section will be rewritten in more detail''


 * Recursive: If this module uses other modules, migrate them first.
 * Copy the module and its documentation page from the local wiki to the global repo. Add sitelinks to them in the module’s Wikidata item.
 * Make the module translatable:
 * Find all the human-readable strings.
 * Move all the strings to a separate storage and replace them with message keys in Lua code (how will this actually work is to be determined, see .)
 * Make the strings translatable using Translate:
 * Make sure that it’s conveniently discoverable in the project selector.
 * Add message documentation (known as "qqq" in core and extensions) so that translators would understand the context.
 * Apply the usual best practices from the page.
 * Make the module usage documentation translatable as a translatable page. (TODO Consider creating association between the UI strings translation and the documentation translation.)
 * Delete the module and its documentation from the local wiki.
 * Test that the module still works as expected in the local wiki. Fix if needed.
 * Go over each wiki in which the module exists:
 * If the code is the same as the one in the global repo:
 * Translate the module’s strings into the wiki’s language.
 * Delete it from the local wiki.
 * If the code is different:
 * Was the module imported some time ago, left unchanged, and updated in the other wiki? If the updates there are good and the parameters are compatible with the current usage in the local wiki, delete it from the local wiki and switch to using the global module.
 * Was the module imported some time ago, and changed only to adapt it to the local language? Copy the translated strings from the local wiki to the localizable module in the central repo. If there are no other differences, delete it from the local wiki and switch to using the global module.
 * Was the module imported some time ago, and had some non-trivial functional changes? Or is it a module that has similar functionality, but was developed separately? Decide in the local wiki on a case by case basis. The main imaginable decisions are (in no particular order):
 * Stop here and keep the local module.
 * Decide that the local changes are not that important, and delete the local module and switch to the global module.
 * Copy the local changes to the global module, making them usable for all wikis. This must be done only after making sure that they don’t break the module for other wikis and don’t make the global module harder to maintain.
 * Split the local module: Move the local changes to another module, and delete the local module.
 * If you are deleting the module from the local wiki in favor of a global module:
 * Check that the local module and the global module have the same parameters. If not, replace the current invocations of the module to use parameters that are compatible with the global module. This can often be done with a bot, but sometimes may have to be done manually.
 * Test that the global module works as expected in the local wiki. Fix if needed.
 * If you found anything problematic during the migration process, update this guide and document it.

Migrating templates
''TODO: This is only an outline. The section will be rewritten in more detail''

This process is similar to the process for modules, but there are also some differences.


 * Recursive: If this template uses other templates or modules, migrate them first.
 * Copy the template and its usage documentation page from the local wiki to the global repo. Add a sitelink to it in the template’s Wikidata item.
 * Find which CSS styles does the template use. Some of them will be in TemplateStyles, and some of them will be in Common.css or other wiki pages. Copy them to the global repository.
 * Make the template translatable:
 * Find all the human-readable strings.
 * Move all the strings to a separate storage and replace them with message keys in the wikitext (how will this actually work is to be determined, see .)
 * TBD: Another option is to do something like what is done in the TNT system and add tags.
 * Make the strings translatable using Translate:
 * Make sure that it’s conveniently discoverable in the project selector.
 * Add message documentation (known as "qqq" in core and extensions) so that translators would understand the context.
 * Apply the usual best practices from the page.
 * Make the template usage documentation translatable.
 * Make the template’s title and parameter names translatable.
 * Delete the template and its documentation from the local wiki
 * Delete the template’s CSS styles from the local wiki, unless:
 * These styles are also used by other templates that were not yet migrated to the global repo.
 * These styles need to remain customized in the local wiki, and the customizations cannot be moved to the global repo conveniently.
 * Go over each wiki in which the template exists:
 * If the wikitext is the same as the one in the global repo, delete it from the local wiki
 * If the wikitext is different:
 * Was the template imported some time ago, left unchanged, and updated in the other wiki? If the updates there are good and the parameters are compatible with the current usage in the local wiki, delete it from the local wiki.
 * Was the template imported some time ago, and changed only to adapt it to the local language? Copy the translated strings from the local wiki to the localizable template in the central repo. If there are no other differences, delete it from the local wiki.
 * Was the template imported some time ago, and had some non-trivial functional changes? Decide in the local wiki on a case by case basis. The main imaginable decisions are (in no particular order):
 * Stop here and keep the local template.
 * Decide that the local changes are not that important and delete the template.
 * Copy the local changes to the global template, making them usable for all wikis. This must be done only after making sure that they don’t break the template for other wikis and don’t make the global template harder to maintain.
 * Split the local template: Move the local changes to another template, and delete the local template.
 * If the template was deleted from the local wiki:
 * Delete the template’s documentation.
 * Delete the template’s CSS styles from TemplateStyles or CSS wiki pages, unless these styles need to remain customized in the local wiki, and the customizations cannot be moved to the global repo conveniently.
 * Test that the template still works as expected in the local wiki. Fix if needed.
 * If you found anything problematic during the migration process, update this guide and document it.

Cross-wiki diff
A tool that shows a diff between revisions of wiki pages on two separate wikis. This would be useful for checking whether the module or the template is the same as on another wiki or the global repo.

Dependency look up
A tool that gets a list of the templates and the modules that a given template or module uses, and checks which ones are already global

Module string migrator
A tool that finds all the strings in Lua code and helps migrate the human-readable ones to message storage and replace the strings in the code with message keys.

Template string migrator
A tool that finds all the strings in wikitext and helps separate them from wikitext by migrating them to message storage and replace the strings in the code with message keys or by adding tags.

When the dust settles
''TODO: This is only an outline. The section will be rewritten in more detail''


 * Some issues to address:
 * Where are the new modules and templates created?
 * How are changes coordinated between different wikis?

Looking even further into the future
''TODO: This is only an outline. The section will be rewritten in more detail''


 * Making templates semantic: making them accessible from VE toolbar, more machine readable, etc.
 * Wikilambda