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.
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.
Specifically, any wiki using a language that provides a localized message for one of these Cite extension messages may 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
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.
Is there any help with writing these CSS rules?
Yes, we have some useful resources for you to write up these rules.
You can use these as starting points to update your wiki's MediaWiki:Common.css . Depending on how 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.
Programmatically generated CSS rules
We wrote a script to process all the localization messages (on wiki and in the Cite extension) and generated CSS rules for your wiki. You can find them here. For your wiki, these rules may work out of the box.
CSS rules developed as part of our testing
As part of visual diff testing, we have had to add a number of these CSS rules to the testing repo. You can see these rules here . These are compatible with the generated rules above. But, these may also have some minor additional fixes (for example, for reference groups that have customized CSS) that you might need for your wiki.
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.
Reporting bugs
You can report bugs on Phabricator - please use the Parsoid or Parsoid-Read-Views tag to report your bugs.
Asking for help
You can reach out to the Content Transform Team by posting via the Talk page for this page. You may also be able to find us on IRC, but the talk page is probably the best place since the responses there might also help others.