Merge pull request #9074 from ckeditor/i/8989

Feature (language): Added language dropdown button to support text part language. Closes #8989.

Other (utils): Added `language.getLanguageDirection` helper function allowing to determine text direction based on language code.

Internal (locale): Language text direction detection moved to the `language` utils module.

packages/ckeditor5-core/src/editor/editorconfig.jsdoc

@@ -176,6 +176,25 @@
  * @member {Array.<String>|Object} module:core/editor/editorconfig~EditorConfig#toolbar
  */
 
+/**
+ * The configuration of the editor language.
+ *
+ *		ClassicEditor
+ *			.create( document.querySelector( '#editor' ), {
+ *				language: ... // Editor language configuration.
+ *			} )
+ *			.then( editor => {
+ *				console.log( editor );
+ *			} )
+ *			.catch( error => {
+ *				console.error( error );
+ *			} );
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ *
+ * @interface LanguageConfig
+ */
+
 /**
  * The language of the editor UI and its content.
  *
@@ -197,7 +216,7 @@
  *				console.error( error );
  *			} );
  *
- * Use different languages for the UI and the content using the object syntax:
+ * Use different languages for the UI and the content using the {@link module:core/editor/editorconfig~LanguageConfig configuration} syntax:
  *
  *		ClassicEditor
  *			.create( document.querySelector( '#editor' ), {
@@ -231,7 +250,23 @@
  *
  * Check the {@glink features/ui-language UI language guide} for more information about the localization options and translation process.
  *
- * @member {String|Object} module:core/editor/editorconfig~EditorConfig#language
+ * @member {String|module:core/editor/editorconfig~LanguageConfig} module:core/editor/editorconfig~EditorConfig#language
+ */
+
+/**
+ * Allows to use different language for the editor UI.
+ *
+ * The language codes are defined in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) standard.
+ *
+ * @member {String} module:core/editor/editorconfig~LanguageConfig#ui
+ */
+
+/**
+ * Allows to use different language of the editor content.
+ *
+ * The language codes are defined in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) standard.
+ *
+ * @member {String} module:core/editor/editorconfig~LanguageConfig#content
  */
 
 /**

packages/ckeditor5-language/CONTRIBUTING.md

@@ -0,0 +1,4 @@
+Contributing
+========================================
+
+See the [official contributors' guide to CKEditor 5](https://ckeditor.com/docs/ckeditor5/latest/framework/guides/contributing/contributing.html) to learn more.

packages/ckeditor5-language/LICENSE.md

@@ -0,0 +1,17 @@
+Software License Agreement
+==========================
+
+**CKEditor 5 Language feature** – https://github.com/ckeditor/ckeditor5-language <br>
+Copyright (c) 2003-2021, [CKSource](http://cksource.com) Frederico Knabben. All rights reserved.
+
+Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html).
+
+Sources of Intellectual Property Included in CKEditor
+-----------------------------------------------------
+
+Where not otherwise indicated, all CKEditor content is authored by CKSource engineers and consists of CKSource-owned intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource with their express permission.
+
+Trademarks
+----------
+
+**CKEditor** is a trademark of [CKSource](http://cksource.com) Frederico Knabben. All other brand and product names are trademarks, registered trademarks or service marks of their respective holders.

packages/ckeditor5-language/README.md

@@ -0,0 +1,16 @@
+CKEditor 5 language feature
+========================================
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-language.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-language)
+[![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-language/status.svg)](https://david-dm.org/ckeditor/ckeditor5-language)
+[![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-language/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-language?type=dev)
+
+This package implements language support for CKEditor 5.
+
+## Documentation
+
+See the [`@ckeditor/ckeditor5-language` package](https://ckeditor.com/docs/ckeditor5/latest/api/language.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
+
+## License
+
+Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html). For full details about the license, please check the `LICENSE.md` file or [https://ckeditor.com/legal/ckeditor-oss-license](https://ckeditor.com/legal/ckeditor-oss-license).

packages/ckeditor5-language/docs/api/language.md

@@ -0,0 +1,26 @@
+---
+category: api-reference
+---
+
+# CKEditor 5 Language feature
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-language.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-language)
+
+This package implements language features support for CKEditor 5.
+
+## Installation
+
+```
+npm install --save @ckeditor/ckeditor5-language
+```
+
+## Contribute
+
+The source code of this package is available on GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-language.
+
+## External links
+
+* [`@ckeditor/ckeditor5-language` on npm](https://www.npmjs.com/package/@ckeditor/ckeditor5-language)
+* [`ckeditor/ckeditor5-language` on GitHub](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-language)
+* [Issue tracker](https://github.com/ckeditor/ckeditor5/issues)
+* [Changelog](https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md)

packages/ckeditor5-language/lang/contexts.json

@@ -0,0 +1,5 @@
+{
+	"Language": "Toolbar button tooltip for the text part language feature.",
+	"Choose language": "Default label for the text part language dropdown.",
+	"Remove language": "The label of the remove language option for the text part language dropdown."
+}

packages/ckeditor5-language/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@ckeditor/ckeditor5-language",
+  "version": "26.0.0",
+  "description": "Language feature for CKEditor 5.",
+  "keywords": [
+    "ckeditor",
+    "ckeditor5",
+    "ckeditor 5",
+    "ckeditor5-feature",
+    "ckeditor5-plugin"
+  ],
+  "main": "src/index.js",
+  "dependencies": {
+    "ckeditor5": "^26.0.0"
+  },
+  "devDependencies": {
+    "@ckeditor/ckeditor5-core": "^26.0.0",
+    "@ckeditor/ckeditor5-dev-utils": "^24.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^26.0.0",
+    "@ckeditor/ckeditor5-engine": "^26.0.0",
+    "@ckeditor/ckeditor5-paragraph": "^26.0.0",
+    "@ckeditor/ckeditor5-theme-lark": "^26.0.0",
+    "@ckeditor/ckeditor5-ui": "^26.0.0",
+    "webpack": "^4.43.0",
+    "webpack-cli": "^3.3.11"
+  },
+  "engines": {
+    "node": ">=12.0.0",
+    "npm": ">=5.7.1"
+  },
+  "author": "CKSource (http://cksource.com/)",
+  "license": "GPL-2.0-or-later",
+  "homepage": "https://ckeditor.com/ckeditor-5",
+  "bugs": "https://github.com/ckeditor/ckeditor5/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ckeditor/ckeditor5.git",
+    "directory": "packages/ckeditor5-language"
+  },
+  "files": [
+    "lang",
+    "src",
+    "theme",
+    "build"
+  ],
+  "scripts": {
+    "dll:build": "webpack"
+  }
+}

packages/ckeditor5-language/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module language
+ */
+
+import TextPartLanguage from './textpartlanguage';
+import TextPartLanguageEditing from './textpartlanguageediting';
+import TextPartLanguageUI from './textpartlanguageui';
+
+export default {
+	TextPartLanguage,
+	TextPartLanguageEditing,
+	TextPartLanguageUI
+};

packages/ckeditor5-language/src/textpartlanguage.js

@@ -0,0 +1,85 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module language/textpartlanguage
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+
+import TextPartLanguageEditing from './textpartlanguageediting';
+import TextPartLanguageUI from './textpartlanguageui';
+
+/**
+ * The text part language feature.
+ *
+ * This feature allows setting a language of the editor's text part to support
+ * [WCAG 3.1.2 Language of Parts](https://www.w3.org/TR/UNDERSTANDING-WCAG20/meaning-other-lang-id.html) specification.
+ *
+ * To change UI editor language, refer to {@glink features/ui-language setting the UI language} guide.
+ *
+ * For more information about this feature check the {@glink api/language package page}.
+ *
+ * This is a "glue" plugin which loads the
+ * {@link module:language/textpartlanguageediting~TextPartLanguageEditing text part editing feature}
+ * and {@link module:language/textpartlanguageui~TextPartLanguageUI text part language UI feature}.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class TextPartLanguage extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ TextPartLanguageEditing, TextPartLanguageUI ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'TextPartLanguage';
+	}
+}
+
+/**
+ * The available {@link module:language/textpartlanguage~TextPartLanguage}
+ * options allowing setting language of parts of the content.
+ *
+ * This configuration option is available only with {@glink api/language language feature} enabled.
+ *
+ * Refer to [WCAG 3.1.2 Language of Parts](https://www.w3.org/TR/UNDERSTANDING-WCAG20/meaning-other-lang-id.html) specification
+ * to learn more.
+ *
+ * To change UI editor language, refer to {@glink features/ui-language setting the UI language} guide.
+ *
+ * The default value is:
+ *
+ *		const config = [
+ *			{ title: 'Arabic', languageCode: 'ar' },
+ *			{ title: 'French', languageCode: 'fr' },
+ *			{ title: 'Spanish', languageCode: 'es' }
+ *		];
+ *
+ * The `title` property will be used by the text part language dropdown to render available options.
+ *
+ * The `languageCode` property is used for the lang attribute in [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format.
+ *
+ * You can also specify optional `textDirection` property indicating the reading direction of the language.
+ * Correct values are `ltr` and `rtl`. When `textDirection` property is missing, the text part language feature will
+ * specify text direction by itself.
+ *
+ * @member {Array.<module:language/textpartlanguage~TextPartLanguageOption>}
+ * module:core/editor/editorconfig~LanguageConfig#textPartLanguage
+ */
+
+/**
+ * Text part language feature option descriptor.
+ *
+ * @typedef {Object} module:language/textpartlanguage~TextPartLanguageOption
+ * @property {String} title The user-readable title of the option.
+ * @property {String} languageCode The language code in ISO 639 format.
+ * @property {'ltr'|'rtl'} [textDirection] The language text direction. Automatically detected if omitted.
+ */