Supporting RTL languages

[bjesus]

Hi,
I've chosen Wagtail as the CMS for a big website our company runs. I'm in the process of integrating it into our current Django website, but I need the admin interface to be in all in Hebrew, and therefore, in RTL.

I've signed up on Transifex and requested (?) Hebrew so I can do the translation. Is this the right process?
Also, I guess the best way to RTL the admin interface is to have a separate CSS file that's loaded only for RTL languages. I'd be happy to write this CSS file, but I'm not sure how and where should I include it, and what would be best as way to contribute back to the project and not only to have a local hack. Any ideas?

Thanks.

[tomdyson]

Hi @bjesus, it looks like you've successfully started the translation, which is excellent - thanks very much.

@davecranwell, can you please reply on RTL support? I hadn't realised that a separate CSS file was necessary.

[davecranwell]

Hi @bjesus. My main consideration is that if you were to submit a PR for RTL support it would be difficult for the Wagtail core team to support it in ongoing work since none of us are familiar with RTL languages. (You could always submit ongoing PRs for RTL updates, but this process would be slow and quite frustrating for you!)

Perhaps the best way might be if you create a new wagtail app which you maintain yourself outside the Wagtail repository. You'd install the app like any other in INSTALLED_APPS and you'd create override templates for skeleton.html and/or admin_base.html (and any others you need) in which you add the dir attributes to the HTML at appropriate points, and add the RTL-specific CSS file too.

We've been meaning to create a list of third party Wagtail apps, and we'd be very happy to list yours if this way suited you.

[tomdyson]

Hi @bjesus. To clarify, we would love to have proper RTL support in core. We think that promising this to our users requires an expert contributor (you?) who can commit to keeping RTL styles up to date with any significant change in the UI. But perhaps it's simpler than we're imagining. What do you think?

[bjesus]

Hi,
I do tend to believe that this issue can be solved by CSS alone, without touching the admin's template files. That's the main reason I rather not create a new django app, but just have the file included if the language is an RTL one (Arabic, Hebrew, etc), but it's really up to you of course. Another option is maybe to give a special class (named "rtl" for example) to the element and then simply add .rtl specific rules to the base SCSS files.

I see our organization using Wagtail for a few years from now, so I believe we can do the maintaining of the stylesheet as it's really not a big deal. At the worst case though, it seems to me that having a mostly RTL'ed interface which some "new elements" shifting to the left is always better than having the whole interface inverted (which is how it is today for RTL languages :-) ).

[davecranwell]

If you're happy to maintain the RTL styles then we're happy to accept PRs which add RTL styles into wagtail core :)

As for doing it all through one CSS file or many, I suppose it depends how much CSS you believe would be needed. If you're going to need to alter every component it might be best to try adding a section at the bottom of each existing file to cope with RTL, triggered by the addition of an rtl class or dir attr on the body or similar. If the code is much simpler however, an rtl.scss that gets @included at the bottom of main.scss might be all it needs?

Just adding dir="rtl" to the html tag does quite a lot, so perhaps the changes would be smaller than expected

[bjesus]

Hi,
As far as I can see there's no need to adjust each and every element, so probably adding an rtl.scss file and and including it within main.scss is the best approach. Then I can do to the maintenance there with less conflicts. Is that fine?

Thanks!

[davecranwell]

That sounds good to me.

[davecranwell]

PR #1534

[thibaudcolas]

New PR: #5058.

[thibaudcolas]

#5058 has gone a long way towards having support for a RTL admin interface, but there's more refactoring work to do. If anyone's interested in this please consider contributing to this. There is also #5263 which is a more incremental change, but still valuable.

I see that the admin UI is 96.3% translated in arabic, so feels like there are lots of people out either having their own custom styles, or looking at text displayed the wrong way around, but in any case who would want to see this fixed.

[zerolab]

https://www.rtlstyling.com/posts/rtl-styling/ looks like a great resource on RTL styling.
Sharing here for future reference

[thibaudcolas]

Based on @zerolab’s resource above and my own research, it looks like the best approach for this in Wagtail would be:

• Switching to logical properties and values where we currently use physical ones.
• Potentially, refactoring layout code to use Flexbox and Grid, since both of these are based on the writing mode of the document.

I don’t think the switch to logical properties would be that much work if anyone wants to get started with this. We’ll need to set up https://github.com/csstools/postcss-logical as well for better browser support for the time being.

---

If anyone wants to work on this, I think a more reasonable approach would be to do this component-by-component rather than "the whole admin at once". This minimises the risk of PRs falling out of date.

Edit: resource on this component by component: https://spectrum.adobe.com/page/bi-directionality/.

[zerolab]

An additional resource: https://www.chenhuijing.com/blog/css-for-i18n/

[thibaudcolas]

We’re almost there with #6170, at which point supporting RTL languages should largely be a matter of switching our stylesheets to logical properties. A great deal should be achievable with relatively mechanical conversion to those properties, with little expert knowledge needed. If anyone wants to work on this, now is a good time to start so we can have RTL support in Wagtail 2.14.

My preference would be to start doing this with a few components as a trial, so we can further validate this approach, and see tangible improvements. In particular, document the steps taken to achieve the RTL-friendly styles, and provide guidance on how you tested the changes.

[amrht]

May I know how are you planning to implement this RTL Change. What are things we need to consider doing this and do we just need to change the positions of components and text or is there anything else that you are planning?

[thibaudcolas]

@amrht do those links help? #8017 and #8051.

[thibaudcolas]

I have converted this from a GitHub issue to a discussion thread, as we’re about to start work on this. At this stage I don’t think it’s terribly useful for us to have a single "pass/fail" issue – we’re going to be rolling this out across Wagtail over many releases, we’ll have to do tooling setup, documentation updates, and we’ll likely say we "support" RTL languages earlier than when we’ve definitely fixed all the bugs everywhere.

---

We’re going to work on this as part of the page editor 2022 redesign, and at this stage we badly need feedback on our approach:

• Looking at the designs shared on that thread – do people familiar with RTL languages have any specific concerns?
• What should we even look for when reviewing designs with RTL compatibility in mind?
• Reviewing the plan above to use CSS logical properties, CSS grid and flexbox – does any of this sound inappropriate? Any other suggestions for how to do it implementation-wise?
• Are there any common gotchas we’re likely to have missed?

[fabienheureux]

I finally got a reply from a client of mine regarding RTL, I was asking for good examples of rtl websites from a user point of view.
Not surprisingly, Al Jazeera came up (https://www.aljazeera.net/ / https://www.aljazeera.com/).
However, the design looks a bit different and these two versions might not use the same version of the codebase.
Switching the direction property from rtl to ltr does most of the required changes though, so it can be a good start to check for ideas.

Here is a form example on both versions https://network.aljazeera.net/ar/contact-us / https://network.aljazeera.net/contact-us

I did not get clear answers to the questions asked regarding what should we look for when reviewing designs.

---

About your plan, it looks good, there is also a lot of information in this guide https://rtlstyling.com/posts/rtl-styling
Based on this last link, I will highlight some currently used properties that might need to be cleaned up shortly

[fabienheureux]

@thibaudcolas regarding this change, before considering a full code refactoring, what do you think of adding https://github.com/csstools/stylelint-use-logical in order to prevent any addition to the current codebase that would go against logical properties ?

[thibaudcolas]

We’ve already done this, although a simpler version: wagtail/stylelint-config-wagtail#10. I chose not to use this particular stylelint plugin as I believe there’s no reason for us to stop using top and bottom physical positioning if we want to. Could still revisit this if this is an issue though.

[fabienheureux]

Ah. my bad, thanks for pointing me to the right file.

[lb-]

A few updates on progress in this area

• WIP PR to adopt CSS logical properties Convert all UI code to CSS logical properties #8051
• Merged PR in the wagtail stylelint config to enforce CSS logical properties Use stylelint built-in rules to disallow left/right positioning stylelint-config-wagtail#10
• Larger discussion about internationalisation / i18n across Wagtail - mainly to gather ideas, feedback and hopefully start on more concrete steps Internationalisation / i18n - testing and guidelines 🌐 #8017

We would love to keep getting ideas on the #8017 discussion - as there is a lot of work underway for the 2022 Page Editor refresh, and where possible, we want to set up new things well.

[thibaudcolas]

#8051 has been merged (thank you LB for the review). I have created three follow-up issues which I think would be nice ones for people interested in RTL support to contribute to:

• Review (and clean up) over-reliance on inset positioning in styles #8125
• Review and replace usage of float layouts in admin UI for RTL support #8126
• Implement icons mirroring of directional icons for RTL languages support #8127

RTL support is getting there but there is still a fair amount of changes needed for the whole of the admin to mirror.

[thibaudcolas]

Discussed in today’s UI team meeting – @fabienheureux is picking some of this up, it feels like we’re not far off full support. He’s going to review float usage in particular, and which icons should and shouldn’t be mirrored.

Here is a CodePen we put together with all the icons to collate whether they should be mirrored or not: https://codepen.io/thibaudcolas/pen/qBobgWG?editors=1000.

[ammarhararah]

Are you still working on this guys?
Can I help in the development process? who is working on this now?
Thanks for your great efforts!

[thibaudcolas]

We are! We’re more or less at the same place as I mentioned in #7793 (comment), though with a better approach for one of the points not mentioned on this list (mirroring of CSS transforms and other physical properties).

Take a look at those three issues I linked to if you want to help, or at the icons mirroring work I shared above, or try out a recent version of the CMS and let us know what other issues there might be.

[thibaudcolas]

For anyone keen to help with this but not necessarily able to easily access a Wagtail site – here is a snapshot of Wagtail 5.1 in Arabic. This isn’t a real Wagtail instance, just a snapshot of the HTML – so lots of parts of the CMS won’t work as expected, but I hope this will be helpful nonetheless.

At this point the main blocker to RTL support in Wagtail is people with RTL language expertise or experience pointing out what the problems are and drafting solutions. We have some sense of common issues (see above) but it’s hard to notice what else might be amiss.

Our fav resources for people who want to get up to speed:

• Spectrum: Bi-directionality – succinct guidelines from Adobe’s design system
• RTL Styling 101 – very comprehensive guide
• Internationalisation / i18n - testing and guidelines 🌐 #8017 – proposed more specific guidelines for Wagtail

[benenright]

Hi all

I have reviewed our existing icon set and made some recommendations for how we treat the icons for RTL languages - based on the best practices outlined in the resources shared above inc. https://m2.material.io/design/usability/bidirectionality.html#mirroring-layout

See here:
https://www.figma.com/proto/h67EsVXdWsfu38WGGxWfpi/Wagtail-CMS?type=design&node-id=5172-30781&viewport=-10001%2C2511%2C0.57&t=s0eS5pOhk3j23hAg-0&scaling=scale-down-width&starting-point-node-id=5172%3A30781&show-proto-sidebar=1&hide-ui=1

In summary:

• We mirror the majority of icons, but there are some exceptions where mirroring would be counter-intuitive (e.g's include: universally recognised western symbols such as text editing actions, universally recognised objects such as a clock, magnifying glass etc.).
• In a couple of cases we have a non-symmetrical icon that contains a combination of elements (e.g 'Tasks' checklist) where it is not recommended to mirror the 'tick' symbols but the list itself would make more sense to appear RTL. So in these cases I have proposed an alternative icon:

[thibaudcolas]

👋 I’m looking for help from people who speak right-to-left (RTL) languages (Hebrew, Arabic, and Persian, and any other), as part of our goal to support Right-To-Left languages in the next release.

Can you help us by spotting any issues in Wagtail which haven’t already been reported here? We’re already aware of icons not being properly mirrored, and of which translations are missing – are there any other glaring issues?

To help with testing, I’ve set up two snapshot copies of the Wagtail admin:

• Wagtail 5.2 in Arabic
• Wagtail 5.2 in Persian

Please report any issues you spot in this thread.

Once we have enough reports, we will proceed with:

• Implement icons mirroring of directional icons for RTL languages support #8127
• Review and replace usage of float layouts in admin UI for RTL support #8126
• RTL: inline comments  #9915
• …and any other fixes as needed

[thibaudcolas]

Thanks @badr4y! Yes, there’s lots of float usage which we want to switch to flexbox.

I think your report there is a pretty great contribution. What do you want to do next? Here are the options that come to mind:

1. Documents, Reports, Images – "some other section" – could use more testing and reporting of specific issues? We want all of Wagtail to work
2. Lacking translations – it’d be great to add as many as possible (https://explore.transifex.com/torchbox/wagtail/)
3. The select tags' pointer is mixed with the option – this is completely new to me. Investigate further, open a new issue about this, work on a PR?

What do you think?

[badr4y]

I'll investigate the select tag bug and work on a PR as soon as possible.
Separately, I'll be adding more translations.

[thibaudcolas]

@badr4y please ping me on Slack and here when you have that PR opened 🙌

[badr4y]

@thibaudcolas Here is the PR I worked on #11313 (comment)

[thibaudcolas]

Thank you @badr4y, I was able to merge this now.

[faagour]

Hi @thibaudcolas,
These are some of the issues that I gathered in the persian version:

1. The admin and account icons should be on the right side of the page :

2. lack of translation (btw I added some translations in the link : (https://explore.transifex.com/torchbox/wagtail/ )

3. Changing the order of the picture and the description ( It is not wrong, but it is better do this for RTL languages

4. When I click and try de create a page with wagtail, the language change totally

[thibaudcolas]

Thanks @faagour! That last one is my mistake with the demo site setup. The other ones are definitely for us to fix.

lack of translation (btw I added some translations in the link : (explore.transifex.com/torchbox/wagtail )

Some of the text you highlight is definitely missing translations. Some are user names or names of pages of the demo site. It wouldn’t be appropriate for the site’s content to be localised – it just depends on what languages the site supports.

Changing the order of the picture and the description ( It is not wrong, but it is better do this for RTL languages

Could you say more about this? I’m surprised by your report, but if it’s indeed better the other way around this would be a nice one for you to make code changes for if you’re keen.

[faagour]

Hi @thibaudcolas!
I think I was mistaken because it seemed to me from my point of view that a change was necessary, but I searched on other web sites wich were written on RTL languages and found that they were using the same thing .

Otherwise, I have a remark which is about the scroller. I think it would be better if it was on the right side

there are some examples of famous web sites in Arabic (Aljazera, Alarabiya, Facebook in arabic ) , and they did exactly this

[faagour]

Hi @thibaudcolas ,

in the example above that I gave it is for the sites Aljazira, Facebook in Arabic and Alarabiya. I think we can take inspiration from them.

[thibaudcolas]

Thanks @faagour! This is surprising to me as I’d have thought "where to show the scrollbar" was for the browser to figure out on its own, rather than sites having to customise this.

Our reference material for RTL adjustments so far has been RTL Styling 101, which suggests browsers do move the scrollbar like Wagtail does.

Can you say why you think the scrollbar should be on the right side?

[thibaudcolas]

Update: the UI is looking solid now. We have about 20 days until we release Wagtail 6.0, where this new UI will ship. One remaining gap is translations – is anyone interested in helping with this, or know people who would be interested?

Tagging @bjesus @fabienheureux @ammarhararah @badr4y @faagour in particular since you’ve been involved with this already.

Improving translations

Please see our documentation for translation contributors. Here is a record of how well Wagtail is translated across multiple languages, on Transifex.

As of today, here is where RTL languages stand:

• Persian: 56%
• Arabic: 49%
• Hebrew: 27%