Parsoid/Parser Unification/Cite CSS

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  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  namespace on a particular wiki. That is, for a given language  and message   (to take a specific example) in order to determine if your language is affected, you should check to see if   has non-default content; this should include both wiki-specific overrides as well as any defaults set in   in the   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 '''TODO: Looks like we also need to look at pages with the title prefix. I will need to update the script on gerrit to process these pages on the wikis.'''
 * 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:.

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  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.

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  which you will need to add. You can check whether your wiki has site-specific overrides in the  namespace to determine if you need to add CSS rules in.

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. 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.