Page MenuHomePhabricator

Supporting directionality for references
Closed, ResolvedPublic


I started to work on this a while ago, but didn't have time to finish it. As this is a needed and useful feature, I'm asking here to seek attention from other developers.

Cite should support directionality for references. It can be accomplished by adding a new param to the <ref> tag like this:

<ref dir="rtl"> ...

which would make the output LI elemnt to render like this:

<li dir="rtl"> ...

In order to make sure the margins and paddings of the LI elements are rendered correctly, I suggest using a CSS class for it like <li class="rtl-reference"> .rtl-reference{ direction:rtl}

Also, "ltr" should be supported too (to be used on rtl wikis). The default direction will be that of the wiki, of course.

Link to discussion on Meta about implementation approach:

Event Timeline

bzimport raised the priority of this task from to Low.Nov 21 2014, 10:08 PM
bzimport added projects: Cite, I18n.
bzimport set Reference to bz13673.
bzimport added a subscriber: Unknown Object (MLST).

sharon.dagan wrote:

Bidirectional references are already supported:

Hello World<ref group="hebrew">HEBREW TEXT HERE (WHICH IS RTL)</ref>
How are you doing<ref>Book of kings, p.123</ref>



Hebrew Refs

<div dir="rtl">
<references group="hebrew"/>

Thanks Sharon for pointing it out. However, that way the order of references changes for the sake of grouping. What I'm suggesting here is that references should all be shown with one <references/> tag in the same order as if they were all in LTR, but RTL ones are handled correctly (or vice-versa if the content language is RTL itself). I'm reopening the bug since what you suggested is a workaround rather than a solution.

sharon.dagan wrote:

Do you think it would be visually appealing to mix LTR and RTL references in the same block?

(In reply to comment #3)

Do you think it would be visually appealing to mix LTR and RTL references in
the same block?

I totally understand what you mean. However, the fact that this has been required in a large scale RTL wiki like Persian Wikipedia, may be provided as a proof for its being appealing :) Anyways, this is possible and (I believe) easy to incorporate LTR and RTL refs, and I don't have a good reason not to do so (although I don't have a good reason pro either).

For the record, using "group" attribute is not a solution anymore, because the name of the group is shown in the citation number in the text.

I'm not sure what is the best solution here: Mixed RTL and LTR lists doesn't look well, but English reference shown as RTL looks bad too.

In Hebrew Wikipedia I created a hack for setting the directionality using some CSS and overriding the reference name:
in common.css I added the following CSS
li[id|="cite_note-hebrewRTL"] {


li[id|="cite_note-LTR"] {



and users can exlicity set the direction by giving name to ref with the correct prefix:
<ref name="LTR-source">LTR reference</ref>
<ref name="hebrewRTL-source">RTL reference (which used when most of the references are LTR and the <references/> it wrapped by dir="ltr")</ref>

An example to it:

However, this hack uses CSS rules that are not supported by old browsers, and it isn't user friendly.

Another [wrong] solution is to use the new dir="auto": the message MediaWiki:Cite_references_link_one could just declare dir="auto" for the li - this currently works only in Chrome. it doesn't requires the user to declare the direction of each reference, but sometimes users may want to explicitly define the direction (example: <ref>Google הוא מנוע חיפוש</ref>).

The CSS based solution you have provided here, is exactly what I requested in the first place. It was questioned if it is appealing or not. Now that two large RTL wikis want this (FaWP and HeWP) and one of them has implemented this (HeWP), I think it is obvious that this is a necessity that should be addressed.

The problem with your approach is not only about lack of support for older browsers. It also makes it impossible to use the "name" attribute for its actual intended purpose. The solution I proposed in the beginning, allows for selectively marking reference as RTL, such that:

<ref dir="rtl">blah</ref>

generates something like:

<li class="citation-rtl">....

and we can define a class for that in the CSS.

Thanks for the patch, but the the look of the resulting comment is quite weird. In the following case, the wiki is LTR, the first comment is LTR and the second is RTL:

  1. ↑ First English comment.

It would be less weird this way:

  1. ↑ First English comment.

The layout at the bottom of is relatively better:

  1. ↑ First English comment. .SECOND HEBREW COMMENT ↑ .2
  2. ↑ Third English comment.
  3. ↑ Fourth English comment. .FIFTH HEBREW COMMENT ↑ .5

... But still, putting the comment numbers on different sides of the page is very weird.

In printed Hebrew books the numbers are always on the right and the alignment is always to the right, even if the comment is in an LTR language.

In an RTL wiki I would align comments to the left only if all of them are LTR.

If all citations are in the same direction (regardless of whether it is the same as the directionality of the wiki content), there is no need to use this new feature. Instead, the whole section can be wrapped in a div, with its directionality set to the desired direction.

The use of this feature is only when some (and not all) of the citations are in the direction opposite to the directionality of the content. I am in support of allowing the direction to be set for the LI element itself. Unlike Amir, I think the layout is not weird. In Persian text, this form of numbering is quite frequent for footnotes and citations.

Last but not least, wrapping the inside of ref tag in a DIV is not a solution. We actually can do that simply by using <ref><div class="whatever">...</div></ref> so there is no need to implement that DIV in the extension code. The first output in comment #9 can be achieved that way, with no change in the extension.

Therefore, I propose the patch to be modified again, in such a way that the CLASS attribute would be added to the LI element itself, not to a DIV element inside of it.

I modified the latter patch to comply with what is requested in this bug, in

I thought it is a bit weird that the numbers are on different sides, and that is the reason for the div within the ref. Regarding the comment 10# it is not the same as adding div within the ref (<ref><div dir="ltr">...</div></ref>), as the whole comment (including the backlink) is in a the "correct" direction (while keeping the numbers in the same side), and without a line break.

However after the discussion here I changed my mind and the other options are fine (and better than the current situation). I did a small survey in the Hebrew community Wikipedia:
and 4 ppl thought the more correct output is as Huji said (to assign dir to the li), while 4 ppl thought the correct output is as Amir said (directionality within the reference-text+ unicode-bidi: embed) - so it is still not clear what is the correct output :) Maybe we should ask the main RTL communities (fa-wikipedia, ar-wikipedin) what they prefer. If we don't ask them, I think adding the class to the li is fine too.

Code review: Gerrit change 7738.

Assigned to patch submitter.

sumanah wrote:

Assigning to submitter of most recent amended patchset, Antoine Musso.

Patch in Gerrit received a -1, needs rework.

Change 7738 had a related patch set uploaded by Krinkle:
Support directionality for reference

@eranroz what is the status of this? Apart from the need for a massive rebase, what else needs to be done?

I will probably not have time to work on this issue in the next few weeks. but I think that from code perspective it is easy task.
The main issue is what is the correct/desired behavior - it is not totally clear and I would like to have a survey in ar/fa/he for it. (is the numbers (the whole LI) should be dir/aligned even if this cause a mix, or should only the content within the LI be aligned).

Once we agree on the desired behavior we can rebase/rewrite ( ). Also note that Parsoid/VE may require support for it to [enhance users to set dir of refs]

PS 13 by @eranroz is a huge step forward. It works, but needs some polishing.

  • The ordered list needs proper margin and padding. Right now when I add an RTL ref tag in a LTR wiki, in the citations list it is shown right at the edge of the page. In the screenshot below you can see the edge of my browser window (orange is my desktop, white is my browser window) and how close to the edge the citation is appearing.

Capture.PNG (190×793 px, 11 KB)

When viewing that page in RTL view (?uselang=fa), again the LTR citation has proper margins, but the RTL does not:

2.PNG (150×787 px, 8 KB)

  • Next, I change the content language of the wiki (in LocalSettings.php) to be an RTL language, now the exact opposite problem occurs. In RTL view, the LTR is too close to the edge:

3.PNG (165×816 px, 12 KB)

And in LTR view of RTL content, again LTR citation is too close to the edge:

4.PNG (176×810 px, 12 KB)

These should be fixed using CSS. But note that currently, the "correct" margin you see is for the OL element, not the LIs inside of it. The OL element has a 3.2em margin but it is only applied to one side of it (not sure how). It should be applied to both sides.

The next issue with PS13 is that it should check to see if the dir parameter has a valid value or not. Right now, if it finds ltr or rtl it will change the direction accordingly, and if it finds anything else, it just ignore is. I think it should instead show a warning (much like how a warning is shown if a bad value is passed for name or group parameters).

Change 7738 had a related patch set uploaded (by Huji; owner: Eranroz):
[mediawiki/extensions/Cite@master] Support directionality for reference

eranroz raised the priority of this task from Low to Medium.Feb 10 2018, 8:34 AM

Adding Parsing-Team--ARCHIVED for review [there may be future implications on the parsoid (specifically lib/ext/Cite/index.js)]

Change 7738 merged by jenkins-bot:
[mediawiki/extensions/Cite@master] Support directionality for reference

Huji removed a project: Patch-For-Review.

Not marking it as resolved yet, as I am still worried about the way T158523 might be in the way. Will try to test it in the next few days and report back.

Seems like it works in fawiki and but not arwiki and hewiki, tested with this code:

<ref dir="rtl">aaa!!!</ref>
<ref dir="ltr">aaa!!!</ref>
<references />

comparing fawiki and hewiki Special:Version, seems like they run the same code version.

Seems like it works in fawiki and but not arwiki and hewiki, tested with this code:

<ref dir="rtl">aaa!!!</ref>
<ref dir="ltr">aaa!!!</ref>
<references />

comparing fawiki and hewiki Special:Version, seems like they run the same code version.

Answering myself: due to override of system messages (e.g MW:Cite references link one)

This comment was removed by Huji.

Since my previous analysis was inaccurate I deleted it and will provide a new analysis here.

In a test wiki

In my test environment, which consisted of an English and a Persian wiki, everything works as desired. The numbers always appear on the same side (e.g. in the LTR wiki, they are always on the left, regardless of the directionality of the citation itself). The content of the LI element is correctly assigned an appropriate class (e.g. in the LTR wiki, if <ref dir=rtl>...</ref> is used the output LI element has the class mw-cite-dir-rtl), and their text is correctly rendered as well (i.e. the class is properly applied to the LI element by the CSS, and the text reads in the correct directionality.

The alignment of the text always follows that of the Wiki's content language. For instance, an RTL citation inside of a LTR wiki will have an RTL directionality but its text alignment will still be left, not right.

Side note

I personally do not like the choices about the placement of numbers and the alignment of text. In Persian literature, the numbering is actually flipped to the left side, and the text alignment is also changed to left. However, I believe this is to be decided by a bigger consensus, and may vary from one RTL language to the next; after all, our RFC did not provide much insight either. That is why I would rather see this patch merged, and discuss these later in the communities, than to continue to hold onto to the patch, like we did for six years. For the time being, any RTL wiki who prefers the display I find more desirable able can simply add this to their Common.css {
  direction: ltr;
  margin-left: 2.3em;
  text-align: left;

I already added this to Persian Wikipedia. So be ready to notice it as you read the next section. I have also started a local RFC to discuss this choice.

On WMF wikis

On Persian Wikipedia, it works: (note that the CSS mentioned above is also applied)

On English Wikipedia, it *does not work* currently: and when you look at the source of the page, the mw-cite-dir-*** classes are not assigned. Considering that en:Special:Version and fa:Special:Version both state the same version for the Cite extension (namely, 7ba27bb) I find this very perplexing. To the extent that I see in the code, we don't have an option to turn this feature on only for selected wikis, do we?

On Arabic Wikipedia, it also *does not work*:

How is that the case, I could not figure out.

@eranroz do you have any clue why the classes are not assigned in any of the WMF wikis except for fawiki (at least from the ones I have tested so far?)

@eranroz do you have any clue why the classes are not assigned in any of the WMF wikis except for fawiki (at least from the ones I have tested so far?)

I had same question, and answered myself here: T15673#4248285

Oh I see. Well, for ENWP I requested here:

It seems like the only thing that override does is to replace ↑ with ^ so I will try to run a query to determine on how many other wikipedias it is being overridden. If people really like ^ better, we can just change it upstream!

Update: EN WP message has been updated to incorporate the new $4 parameter.

For the record this RFC also came to the conclusion that, at least for Persian literature, it is preferred that the numbering of the references (in the <references/> section) is flipped to the left for LTR references inside RTL text.

This will be enforced automatically, once my patch for T158523 is merged. For now, it is locally enforced using a modification of MediaWiki:Common.css (which I also explained above)

Huji closed this task as Resolved.EditedJun 8 2018, 2:50 PM
Huji claimed this task.

I made a request on arwiki for their local message to be updated as well. At this point, I believe this task can be qualified as complete. Any subsequent issues can be tracked through separate Phab tasks.

I made a request on arwiki for their local message to be updated as well. At this point, I believe this task can be qualified as complete. Any subsequent issues can be tracked through separate Phab tasks.

Message updated on arwiki. Thank you.

Change 558060 had a related patch set uploaded (by Awight; owner: Awight):
[mediawiki/extensions/Cite@master] [WIP] Move "dir" error handling to validation

Change 558060 merged by jenkins-bot:
[mediawiki/extensions/Cite@master] Move "dir" error handling to validation