t/1151: Implemented the right–to–left (RTL) languages support for the UI and the content

docs/_snippets/features/build-ui-language-source.js

@@ -0,0 +1,12 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window */
+
+/* config { "additionalLanguages": [ "ar", "es" ] } */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+
+window.ClassicEditor = ClassicEditor;

docs/_snippets/features/ui-language-content.html

@@ -0,0 +1,4 @@
+<div id="snippet-ui-language-content">
+	<h2>لغة</h2>
+	<p>اللغة نسق من الإشارات والرموز، يشكل أداة من أدوات المعرفة، وتعتبر اللغة أهم وسائل التفاهم والاحتكاك بين أفراد المجتمع في جميع ميادين الحياة. وبدون اللغة يتعذر نشاط الناس المعرفي. وترتبط اللغة بالتفكير ارتباطًا وثيقًا؛ فأفكار الإنسان تصاغ دومًا في قالب لغوي، حتى في حال تفكيره الباطني. ومن خلال اللغة فقط تحصل الفكرة على وجودها الواقعي. كما ترمز اللغة إلى الأشياء المنعكسة فيها.</p>
+</div>

docs/_snippets/features/ui-language-content.js

@@ -0,0 +1,25 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-ui-language-content' ), {
+		language: {
+			content: 'ar'
+		},
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

docs/_snippets/features/ui-language-rtl.html

@@ -0,0 +1,4 @@
+<div id="snippet-ui-language-rtl">
+	<h2>لغة</h2>
+	<p>اللغة نسق من الإشارات والرموز، يشكل أداة من أدوات المعرفة، وتعتبر اللغة أهم وسائل التفاهم والاحتكاك بين أفراد المجتمع في جميع ميادين الحياة. وبدون اللغة يتعذر نشاط الناس المعرفي. وترتبط اللغة بالتفكير ارتباطًا وثيقًا؛ فأفكار الإنسان تصاغ دومًا في قالب لغوي، حتى في حال تفكيره الباطني. ومن خلال اللغة فقط تحصل الفكرة على وجودها الواقعي. كما ترمز اللغة إلى الأشياء المنعكسة فيها.</p>
+</div>

docs/_snippets/features/ui-language-rtl.js

@@ -0,0 +1,23 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-ui-language-rtl' ), {
+		language: 'ar',
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

docs/_snippets/features/ui-language.html

@@ -1,3 +1,3 @@
 <div id="snippet-ui-language">
-	<p>This is <a href="https://ckeditor.com">CKEditor&nbsp;5</a>.</p>
+	<p>Un <strong>lenguaje</strong> (del <a href="http://es.wikipedia.org/wiki/Idioma_occitano">provenzal</a> <em>lenguatge</em> y este del <a href="http://es.wikipedia.org/wiki/Lat%C3%ADn">lat&iacute;n</a> <em>lingua</em>) es un sistema de <a href="http://es.wikipedia.org/wiki/Comunicaci%C3%B3n">comunicaci&oacute;n</a> estructurado para el que existe un <a href="http://es.wikipedia.org/wiki/Significado">contexto</a> de uso y ciertos principios combinatorios formales. Existen contextos tanto naturales como artificiales.</p>
 </div>

docs/_snippets/features/ui-language.js

@@ -3,16 +3,13 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
-/* globals console, window, document */
-
-/* config { "language": "de" } */
-
-import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+/* globals ClassicEditor, console, window, document */
 
 import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
 
 ClassicEditor
 	.create( document.querySelector( '#snippet-ui-language' ), {
+		language: 'es',
 		cloudServices: CS_CONFIG,
 		toolbar: {
 			viewportTopOffset: window.getViewportTopOffsetConfig()

docs/features/ui-language.md

@@ -2,16 +2,32 @@
 category: features
 ---
 
+{@snippet features/build-ui-language-source}
+
 # Setting the UI language
 
 The UI of the editor can be localized. CKEditor 5 currently supports around 20 languages and the number is growing.
 
 If you want to help translate CKEditor 5 into your native language, join the [CKEditor 5 project on Transifex](https://www.transifex.com/ckeditor/ckeditor5/). Your help will be much appreciated!
 
-See the demo of the editor in German:
+See the demo of the editor in Spanish:
 
 {@snippet features/ui-language}
 
+## Right–to–left (RTL) languages support
+
+CKEditor 5 supports right–to–left languages out–of–the–box. When one of <abbr title="right–to–left">RTL</abbr> languages is used, the editor adapts its UI for the best editing experience, for instance, mirroring various elements like toolbars, dropdowns, buttons, etc..
+
+See the demo of the editor in Arabic:
+
+{@snippet features/ui-language-rtl}
+
+<info-box>
+	If you want to change the language of the content only (different languages for the UI and the content), check out the ["Setting the language of the content"](#setting-the-language-of-the-content) section to learn more.
+</info-box>
+
+We are doing our best to deliver the best RTL support to our users and we constantly improve the editor. Check out the ["RTL support"](https://github.com/ckeditor/ckeditor5/issues/1151) issue on GitHub to learn more and stay up–to–date. Thank you for the feedback!
+
 ## Loading additional languages from CDN, npm and zip file
 
  By default, the editor will display in English. This is the language built into the `ckeditor.js` files. In order to change the language of the editor UI, you need to load additional language file(s). Check out the following sections to see how to do that:
@@ -26,7 +42,7 @@ Next, you can configure the editor to use the chosen language:
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		// The language code is defined in the https://en.wikipedia.org/wiki/ISO_639-1 standard.
-		language: 'de'
+		language: 'es'
 	} )
 	.then( editor => {
 		console.log( editor );
@@ -149,3 +165,34 @@ If you build CKEditor from scratch or integrate it directly into your applicatio
 
 	You can read more about the used techniques in the ["Implement translation services" issue](https://github.com/ckeditor/ckeditor5/issues/387) and ["Implement translation services v2" issue](https://github.com/ckeditor/ckeditor5/issues/624).
 </info-box>
+
+## Setting the language of the content
+
+In CKEditor 5 you can separately configure the language of the UI and the language of the content. That means you can use the English UI of the editor but type your content in Arabic or Hebrew. The language of the content has an impact on the editing experience, for instance it affects screen readers and spell checkers. It is also particularly useful for typing in certain languages (e.g. [right–to–left](#righttoleft-rtl-languages-support) ones) because it changes the default alignment of the text.
+
+Configure {@link module:core/editor/editorconfig~EditorConfig#language `config.language`} to change the language of the content. In this example, the UI of the editor will be English but the content will be Arabic:
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		language: {
+			// The UI will be English.
+			ui: 'en',
+
+			// But the content will be edited in Arabic.
+			content: 'ar'
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
+```
+
+{@snippet features/ui-language-content}
+
+<info-box>
+	If unsure what language the content will be typed in, do not set it. The language of the content will then be inherited from the {@link module:core/editor/editorconfig~EditorConfig#language language of the UI}.
+</info-box>

docs/framework/guides/contributing/development-environment.md

@@ -193,7 +193,7 @@ To create a server for manual tests use the `manual` task:
 yarn run manual
 ```
 
-It accepts the `--source-map` (`-s`) option. Note that it watches for changes in the JavaScript files only (see the [bug](https://github.com/ckeditor/ckeditor5-dev/issues/52)).
+It accepts the `--source-map` (`-s`) and `--additionalLanguages="ar,pl,..."` options. Note that it watches for changes in the JavaScript files only (see the [bug](https://github.com/ckeditor/ckeditor5-dev/issues/52)).
 
 You can read more about the {@link framework/guides/contributing/testing-environment Testing environment}.
 

docs/framework/guides/contributing/testing-environment.md

@@ -51,7 +51,10 @@ yarn run test -cw --files=basic-styles/bold*.js
 
 In order to start the manual tests server use the `yarn run manual` task.
 
-The task accepts the `--source-map` (alias `-s`) option.
+The task accepts the following options:
+
+* `--source-map` (alias `-s`) that generates useful source maps for the code.
+* `--additionalLanguages="ar,pl,..."` that passes extra languages to the [CKEditor 5 webpack plugin](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-webpack-plugin). Check out the {@link features/ui-language UI language guide} to learn more.
 
 It starts the server available at http://localhost:8125.