Ckeditor5: RTL support

[Reinmar]

Is this a bug report or feature request? (choose one)

🆕 Feature request

📃 Other details that might be useful

RTL support is a quite wide topic. We need to consider the UI of the editor as well as the editing features.

If you'd like the editor to better support RTL environments (such as Arabic, Hebrew and Persian) please add 👍. You can also comment what's a minimum viable state for you (i.e. what do you expect working first).

Plan

MVP

Basic changes to editor configuration

• [x] RTL languages must be recognized. The easiest way is hardcoding them in some class or utility like in CKEditor 4.
  
  
  
  • Using config.language = 'ar' will change the dir attribute of the editable.
  
  
• [x] [contentLanguage configuration like in CKEditor 4](https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_config.html#cfg-contentsLanguage) is needed.
  
  
  
  • Setting this config will change the lang and dir attributes of the editable regardless of the editor UI language ☝. For instance, allows writing english text with an Arabic UI and vice–versa. Affects screen readers, spell checkers, font selection, etc..
  
  

Changes to the editing layer

• [x] [dir attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) support on the contenteditable element.
  
  
  
  • auto by default leaving the decision up to the UA, which sets the text direction based on the first character with a strong directionality,
  
  
  • it will be changed via UI language content language configurations
  
  
• [x] Text alignment feature must work in RTL environments.
• [x] Block indentation feature must work in RTL environments.
• [ ] Two-step caret movement around links must work in RTL environments.
  
  
  
  • [x] Basics work
  
  
  • [ ] There's an engine issue that breaks it in some cases.
  
  
• [x] Blockquote border should be on the right side in RTL

UI layer

Core changes

• [x] Information about LTR/RTL based on the UI language configuration will be passed via editor Locale which is propagated to all UI components.
• [x] Root UI elements should read the locale object and get .ck-rtl CSS class when necessary.
  
  
  
  • Children will use it as a first selector to set proper styling, for instance .ck-rtl .ck.ck-button { ... }
  
  

Changes in UI components

• Inputs
  
  
  
  • [x] Changing text direction of the InputView
  
  
• Balloons and panels (link balloon, media embed panel, etc.)
  
  
  
  • [x] Action buttons (save, cancel) should be left–aligned
  
  
  • [x] Other buttons, for instance those inside the first step of the link editing should also be aligned in a different way. Generally speaking, the layouts must be mirrored.
  
  
• Toolbars
  
  
  
  • [x] Items should be right–aligned in ToolbarView.
  
  
  • [x] [Inline editor](https://ckeditor.com/docs/ckeditor5/latest/examples/builds/inline-editor.html) toolbar should be on the right side of editable.
  
  
  • [x] [Block toolbar](https://ckeditor.com/docs/ckeditor5/latest/examples/builds/balloon-block-editor.html) should be displayed on the right of the editable.
  
  
• Dropdowns
  
  
  
  • [x] The opener arrow should be on the left side in the RTL
  
  
  • [x] Scrollbar on the left side when RTL (this should probably happen upon changing direction: rtl)
  
  
  • [x] Dropdown panel should open to the left of the button in RTL
  
  
  • [x] When RTL, the arrow for the split button dropdown should be on the left side.
  
  
• Lists
  
  
  
  • [x] List items should be right–aligned in RTL
  
  
• Widgets
  
  
  
  • [x] The selection handler should be on the right side when RTL
  
  

Accessibility

• [ ] In an open dropdown, the left arrow goes back to the parent (toolbar) in LTR. In RTL the right arrow should do that instead.

Beyond MVP

Changes in UI components

• IconView
  
  
  
  • [ ] [Icon localization](https://github.com/ckeditor/ckeditor5/issues/1613) because some icons must change their layout based on the language
    
    
    
    
    
    • [x] Undo/redo
    
    
    
    • [x] Indent
    
    
    
    • [ ] Numbered list
    
    
    
    • [ ] Bulleted list
    
    
    
  
  
• Balloons
  
  
  
  • [ ] The default set of positions should be different for RTL ("west" positions instead of "east" in LTR)
  
  
• Image upload progress should go from the right to the left.

Accessibility

• [ ] In tables the down arrow moves forwards in LTR (cell to the right). In RTL it should move backwards (cell to the left). Same for the up arrow.
• [ ] [Text part language](https://ckeditor.com/docs/ckeditor4/latest/examples/language.html) support as in the spec. It helps screen readers deal with a mixed language content. Supported by the v4 plugin.

BiDi

• [ ] There's a Unicode Bidirectional Algorithm which boils down to searching for a first strong directional character and changing the direction of the block, based on that character. Thanks to that algorithm, each block (usually the paragraph) can have its direction (when different than dir="..." of the editable), which helps editing mixed content and saving it to the database. It obsoletes the CKEditor 4 BiDi plugin.
  
  
  
  • [ ] It can be implemented using a set of RegExps, which are based on official BiDi class definitions. For instance, facebook is using that in their utils.
  
  
  • [ ] The UI of the editor can reflect the direction of the block, e.g. the icons can be mirrored dynamically. More examples.
  
  

Related tickets

• https://github.com/ckeditor/ckeditor5-alignment/issues/3
• https://github.com/ckeditor/ckeditor5-editor-classic/issues/32
• https://github.com/ckeditor/ckeditor5/issues/671

[ilantz]

Please add support for RTL, setting direction based on "strong RTL" characters during input.
Draft.js does this pretty good and allows also per paragraph direction.

[xxyyzz2050]

Please consider adding (dir="auto") to auto set the default direction based on the first detectable charachter

[Kolahzary]

We're switching to CKEditor 4 until implementation of this feature.
It would be much better if we could use toolbar to switch RTL per paragraph

[mohamedsabil83]

We just back to use CKEditor 4 until supporting RTL in CKEditor 5

[mohamedsabil83]

Any news about time to support RTL?

[xsoheilalizadeh]

Thanks for your great editor, we wait for RTL support to upgrade CKEditor 4 to CKEditor 5 version.

[ghost]

Any news about RTL?

[Reinmar]

@oleq research this topic and will share his findings here. We expect to have the most important issues solved until the end of June, but the first improvements should land sooner than that.

[oleq]

Just FYI: I updated the "Plan" section of the first comment with a rough roadmap and listed steps to make the editor RTL–friendly. Please let me know in the comment if there's anything I forgot to mention but should land in the MVP.

[mlewand]

📰 Just an update to all of us following this issue: unfortunately we won't be able to ship this feature in the upcoming iteration. This is a priority issue for us, and we'd like to have it as soon as possible, but the scope of this issue is quite big, as shown in the research. Also it requires more testing. Currently we don't have the required man power to complete this feature.

It's not an official ETA but we should resume the works in June so given the complexity we can expect it to be available somewhere in July. That's just a rough estimation, we'll be updating this issue as we know more.

[dorkalev]

hi, not sure that's the right place to mention it but would love to beta-test/qa/ help in any way. looking forward to this feature.

[Reinmar]

Thanks :)

@oleq, do you have something live? Could we deploy something to ckeditor5.github.io, e.g.?

[oleq]

We're gonna have a PR soon. Stay tuned.

[mohamedsabil83]

We're gonna have a PR soon. Stay tuned.

Good news to hear @oleq. We'll be waiting for it.

[oleq]

Updates...

Hello everyone,

it's been a while, but I've got some news for you.

• First of all, we have a PoC of the RTL support ready for you to check out. The team is counting on your feedback! Have your say and help us deliver the best RTL experience to our community.
• Check out the roadmap to know the scope of the MVP.
• We also noticed that there are some issues concerning typing around links in the PoC when using the RTL languages. We're on it, not sure if we address that in MVP, though. Stay tuned.

Concerns regarding dir="auto"

At this moment, the implementation considers two configurations:

1. config.language
2. config.contentLanguage.

The former configures both the UI language and the content language, if the later is not specified.

config.contentLanguage allows you to override the language of the content (lang attribute on editable) and changes the dir attribute of the editable to match that language.

If config.contentLanguage is not set, the dir is set to auto on the editable to let the Unicode® Bidirectional Algorithm algorithm decide what direction the user is writing in.

The current implementation:

| | config.langugage="en" config.contentLanguage unset | config.langugage="en" config.contentLanguage="ar" | config.langugage="ar" config.contentLanguage unset |
|-----------------|----------------------------------------------------|---------------------------------------------------|----------------------------------------------------|
| UI "lang" | en | en | ar |
| UI "dir" | ltr | ltr | rtl |
| Editable "lang" | en | ar | ar |
| Editable "dir" | auto | rtl | auto |

We noticed that this does not work for editor placeholders. Remove all the content in the demos to see that the placeholder is not considered by that algorithm.

We're considering ditching dir="auto" for that reason and using the rigid dir values depending on the contentLanguage. That would work perfectly for now and since we're considering bi–directional input in the future (see the plan), dir="auto" wouldn't be necessary any longer. That would look as follows:

| | config.langugage="en" config.contentLanguage unset | config.langugage="en" config.contentLanguage="ar" | config.langugage="ar" config.contentLanguage unset |
|-----------------|----------------------------------------------------|---------------------------------------------------|----------------------------------------------------|
| UI "lang" | en | en | ar |
| UI "dir" | ltr | ltr | rtl |
| Editable "lang" | en | ar | ar |
| Editable "dir" | ltr | rtl | rtl |

Is dir="auto" on editable such a dealbreaker? How else could we allow the configuration? Should we use v4's config.contentsLangDirection instead?

[dkonopka]

Two words about concerns regarding dir="auto" - Edge is not supporting it.

According to Microsoft's open specifications, IE/Edge does not support the "auto" keyword on elements. With development of Edge on Chromium nearing completion, adding support on the existing version of Edge is highly unlikely. - see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir

[3alampro]

wow @oleq great work on RTL support I love it

the only issue may occur in the feature I'm not sure though is when we have the code snippets plugin released and content include code blocks and they need to be LTR for correct presentation within RTL content

other than that what i see in the early POC is great and really works

[3alampro]

for the placeholder direction issue I think it will be fixed if you use

text-align: inherit

instead of initial

[oleq]

I'm glad you like it @3alampro!

the only issue may occur in the feature I'm not sure though is when we have the code snippets plugin released and content include code blocks and they need to be LTR for correct presentation within RTL content

The feature you're talking about is the BiDi support we mentioned in "Beyond MVP". It's not a part of this POC and will not land in the MVP.

for the placeholder direction issue I think it will be fixed if you use

text-align: inherit

instead of initial

It doesn't work :( unicode-bidi: plaintext; works. It's not widely supported, though. And I'm still not sure about the consequences.

[AHasanin]

hi,
i am using CKEditor5 in an angular and iam having a problem with text-alignment whenever i change the system language to rtl language the editor treats left-alignment and right-alignment as one for both arabic and english, but it works perfectly when i change the system language to english.

if i use config.contentLanguage or dir ,it does nothing,
hope u coluld help

[oleq]

@AHasanin Confirmed, thanks!

I added the Alignment feature to the PoC and it does not work when in RTL mode.

[Reinmar]

Not sure if anyone pointed this out already, but block indent will (most likely) not work too :D

[rakk7]

Great work, I love it.

I am going to test it more, but for now, when doing a 'block quote', the left border should be on the right.

[mohamedsabil83]

Also, need to fix the inserting side of the table columns.

[oleq]

@mohamedsabil83 What do you mean exactly? Should "Insert column right" be before "Insert column left" in the dropdown list or something else?

[mohamedsabil83]

@oleq No, I mean in the table itself. When "Insert column right", a left column inserted instead and vice versa.

[oleq]

Some follow–up of my previous comment:

I found out dir="auto" set on the editable brings some issues. For instance:

• typing around links is broken when dir is auto. The editor does not know what to do when arrow right/left is pressed because depending on the direction of the text, the response should be different. In LTR content, the right arrow "moves into" the link. In RTL content, the same right arrow can "move out" of the same link.
• The blockquote feature does not know on which side the quote should be styled. It can display a border on the left side (dir="ltr") or on the right side (dir="rtl") but in dir="auto" there's no good choice.

• Same with text alignment feature.

  When the content has dir="ltr", the default editor styles set text-alignment: left and when the user customizes the alignment of the block, the block gets text-alignment: right, center, or nothing (default).

  When the content has dir="rtl", the default editor styles set text-alignment: right and when the user customizes the alignment of the block, the block gets text-alignment: left, center or nothing (default).

  But when the content has dir="auto", things get complicated because there's no sane default in which the block has no text-alignment. The text can be in Arabic but because of dir="auto" it will be aligned left by default (and vice–versa for English text).

We could bring config.contentLanguageDirection (like in v4) for people who want to use dir="auto" for some reason, but I'd rather ditch it by default and go with the 2nd table from my previous comment.

Also, probably all the issues related to dir="auto" will be solved when the editor implements a proper BiDi (bidirectional content support, like in v4). Features like Link or Text alignment will know the direction of the block and they will adapt their behaviour.

[Reinmar]

I've just revied @oleq's work and it's great. There are just minor implementation issues, so I don't see any risk of this work not getting into the next release 🎉

Thanks @oleq! And thank you all for your insights.

[Reinmar]

It's all on master now. Thanks, @oleq and you all! 🎉

There are some followups of course – basically, you can check the state of the implementation in the first post in this thread. But it's a very good first step :)

@oleq, could you extract missing pieces (like Bidi) to separate tickets and label them with feature:rtl label?

[rathiayush]

@oleq @Reinmar Where can i find documentation for rtl ?

[mlewand]

@rathiayush both guide in our CKEditor 5 features section and API docs will be released during this release, which will happen on August 22nd (tomorrow 🎉).

I can see that you might have been mislead by the date set in milestones section, which was set to code freeze date rather than actual npm release date, sorry for that. It has been adjusted now.

[mlewand]

@rathiayush @mohamedsabil83 Just a quick update: this time our QA took a little longer than expected, we discovered an image/table issue that we want to fix. So the npm package is now scheduled to be released on the 26th of August. Sorry for inconvenience.

[mohamedsabil83]

Don't worry @mlewand will be waiting. The main point is supporting bidi a.s.a.p.

[rathiayush]

@rathiayush @mohamedsabil83 Just a quick update: this time our QA took a little longer than expected, we discovered an image/table issue that we want to fix. So the npm package is now scheduled to be released on the 26th of August. Sorry for inconvenience.

@mlewand Just a quick question, will this build contain toolbar option to select RTL and LTR or would it be RTL in editor according to lang selection?

[mlewand]

@rathiayush just like shown in the PoC referenced here it's driven by ui and content language config options. You can read more about this in our (to-be-published on Mon) docs https://github.com/ckeditor/ckeditor5/blob/master/docs/features/ui-language.md

[rathiayush]

@rathiayush just like shown in the PoC referenced here it's driven by ui and content language config options. You can read more about this in our (to-be-published on Mon) docs https://github.com/ckeditor/ckeditor5/blob/master/docs/features/ui-language.md

Are we planning to implement toolbar option to select RTL and LTR in near future?

[oleq]

Are we planning to implement toolbar option to select RTL and LTR in near future?

What would you use that for? In which case the toolbar direction should be different than the UI language direction?

[rathiayush]

Are we planning to implement toolbar option to select RTL and LTR in near future?

What would you use that for? In which case the toolbar direction should be different than the UI language direction?

For writing arabic and english together as it was implemented in ckeditor4.

[mlewand]

@rathiayush Just to be sure, by toolbar option you mean: toolbar configuration option that affects the toolbar, not something like toolbar button, right? (because there was no such thing in CKE4 😉)

Anyway we have a config option to set both ui (which includes the toolbar) and the content as mentioned in https://github.com/ckeditor/ckeditor5/issues/1151#issuecomment-524199290 - hope that's what you're asking for 🙂

[oleq]

For writing arabic and english together as it was implemented in ckeditor4.

You're probably referring to the BiDi feature of CKEditor 4, which allows using a different text direction for each block, which is also dynamically reflected in the UI.

This feature is not available in CKEditor 5 yet but it's on our TODO (beyond MVP) list as stated in the original post.

[rathiayush]

@mlewand @oleq Sorry, I was referring to the BiDi feature of CKEditor 4. good to hear that it's on your TODOs. Thanks

[EhsanJamshidi]

please check this
I use this sample
https://ckeditor5.github.io/misc/rtl-demo/
but pressing space button is not working
weird?!

[Reinmar]

Works for me when I set the keyboard layout to Arabic (not sure if that's your setting). If you think there's a bug, could you report a new ticket and describe what happens (perhaps also record a screencast)?

[abedi-ir]

I wrote the plugin for BiDi
https://github.com/abedi-ir/ckeditor5-direction/

[EhsanJamshidi]

Thanks, I'll check it and let you know

[AHasanin]

@AHasanin Confirmed, thanks!

I added the Alignment feature to the PoC and it does not work when in RTL mode.

any progress on this issue?

[oleq]

@AHasanin Since [email protected] we officially support RTL content and that includes the alignment feature. Update your editor and give it a try!

[mohamedsabil83]

I wrote the plugin for BiDi
https://github.com/abedi-ir/ckeditor5-direction/

Hey @oleq, what about BiDi plugin which introduced by @abedi-ir?

[oleq]

You can use it if it works for you (I haven't seen it yet, though) but keep in mind we don't provide support for 3rd–party plugins.

BiDi is on our TODO list so one day it's gonna be a core editor feature. Unfortunately, I can't share any strong ETA with you.

[mustafa-online]

😢