Parsoid/Parser Unification/Cite CSS
 | This page is currently a draft.
|
Like all extensions, the Cite extension has localized messages. However, a significant portion of the localized messages are for formatting and for localizing the numbering scheme.
Parsoid takes a different approach than the legacy parser and uses CSS to perform the number-format-specific localization of the Cite extension. One of the reasons for this approach is to ensure a good editing experience in editing clients like VisualEditor: when citations are modified (added / removed), using CSS ensures that the numbers adjust automatically and consistently. Otherwise, VE (and other clients) would have to make a server request to re-render all citations each time one is added or removed which can make for a poor and inefficient experience.
Wikis should add appropriate CSS rules to their MediaWiki:Common.css file to ensure proper localization of citations in Visual Editor, given this difference in how citation number localization is performed. This will become even more important as we start to migrate toward the use of Parsoid HTML for readers, not just for editing.
Which wikis are impacted?
Pretty much any wiki that uses localized numbering schemes will be impacted. Specifically, any wiki using a language that provides a localized message for one of these Cite extension messages will need CSS rules for Parsoid HTML
- cite_reference_link
- cite_references_link_many_format
- cite_references_link_many_format_backlink_labels
- cite_references_link_one
- cite_references_link_many
- cite_references_link_many_sep
- cite_references_link_many_and
There are two sources for localization: (1) language-specific localization messages in the Cite extension repository (2) message overrides defined in the MediaWiki namespace on a particular wiki. That is, for a given language br and message cite_references_link_many_format (to take a specific example) in order to determine if your language is affected, you should check to see if https://<your wiki>/wiki/MediaWiki:Cite_references_link_many_format has non-default content; this should include both wiki-specific overrides as well as any defaults set in i18n/<language code>.json in the Cite extension repository.
Language localization files in the Cite extension
The list of 28 language localizations present in the Cite extension are: ar arz ban bcc bn br ce ckb cu en fr frp gag hi ko lez mk nb ru sl sr-ec sr-el th tly ttt uk ur vi.
Addressing localizations in these languages is easier to handle within the Content Transform Team. We are likely to resolve this via T156350 and these rules will be available for all these language wikis on all projects.
Localized Cite messages on a wiki
Some wikis further localize citation formatting by using message overrides in the MediaWiki namespace on that wiki.
Here is the list of 128 wikis that have some site message defined for Cite. Note that just because your wiki is on this list does not mean that it needs a fix. Please see the next section to find out if your wiki is impacted.
| Project | List of wikis |
|---|---|
| Wikipedia | acewiki, amwiki, arbcom_enwiki, arwiki, arywiki, arzwiki, azbwiki, azwiki, be_x_oldwiki, bgwiki, bjnwiki, bnwiki, bswiki, cewiki, ckbwiki, commonswiki, cswiki, cvwiki, dawiki, dewiki, enwiki, eowiki, eswiki, euwiki, fawiki, fiwiki, frpwiki, frwiki, glwiki, guwiki, hewiki, hiwiki, hrwiki, huwiki, idwiki, ilowiki, itwiki, iuwiki, jawiki, jvwiki, kawiki, kkwiki, kowiki, kuwiki, kvwiki, ladwiki, lnwiki, metawiki, minwiki, mrwiki, mswiki, mtwiki, ndswiki, nlwiki, nowiki, nvwiki, ocwiki, pagwiki, plwiki, ptwiki, rowiki, ruwiki, scnwiki, scowiki, shwiki, skwiki, slwiki, sqwiki, srwiki, suwiki, svwiki, test2testwiki, tgwiki, tiwiki, trwiki, ukwiki, urwiki, viwiki, yiwiki, zhwiki |
| Wikiquote | afwikiquote, enwikiquote, eswikiquote, glwikiquote, hewikiquote, hrwikiquote, itwikiquote, ruwikiquote, sqwikiquote, ukwikiquote, viwikiquote |
| Wikisource | cswikisource, dewikisource, fiwikisource, frwikisource, glwikisource, hewikisource, hrwikisource, itwikisource, ruwikisource, vecwikisource, viwikisource, zhwikisource |
| Wikitionary | bswiktionary, dewiktionary, enwiktionary, eswiktionary, frwiktionary, hrwiktionary, kuwiktionary, ocwiktionary, svwiktionary, trwiktionary, viwiktionary, zhwiktionary |
| Wikibooks | enwikibooks, glwikibooks, hewikibooks, jawikibooks, nowikibooks, ruwikibooks, slwikibooks, viwikibooks |
| Wikinews | ewikinews, ukwikinews |
| Wikivoyage | ruwikivoyage |
| Affiliate wikis | ruwikimedia, uawikimedia |
Is there a way to see if my wiki is impacted?
Yes. If you open a page that has citations in VisualEditor, and the citations on the page render differently from outside VE, then your wiki either needs language-specific CSS rules (which we will handle via T156350 as above), or it needs CSS rules to be added to MediaWiki:Common.css which you will need to add. You can check whether your wiki has site-specific overrides in the MediaWiki namespace to determine if you need to add CSS rules in MediaWiki:Common.css.
Examples of CSS rules
As part of visual diff testing, we have had to add a number of these CSS rules to the testing repo. You can use these rules as starting points to update your wiki's MediaWiki:Common.css. Depending on your wiki's CSS is structured, you may not necessarily want to copy-paste these exact rules into your wiki, but those rules will hopefully make it quicker to update your wiki's CSS.
How can we verify changes?
As above, you can open the page in VisualEditor (after ensuring caches are purged) to see if your CSS fixes have improved the rendering of citations.
Who can be reach out for help / reporting bugs
You can report bugs on Phabricator as always (TODO: Be more specific). You can also reach out to the Content Transform Team either on IRC, email, or on wiki here by posting on this talk page. (TODO: Maybe provide a single place for this?)