Globalization

---

---

⚠⚠ ⚠⚠ ⚠⚠

This wiki served in the early days of CKEditor 5 development and can be severely outdated.

Refer to the official CKEditor 5 documentation for up-to-date information.

---

---

Globalization is all about adapting software to different languages and regional differences of the several cultures around the globe. It is composed by two aspects:

• Internationalization: designing features that give to software the potential of being adapted to various languages and regions.
• Localization: the process of adapting software to specific languages and regions.

In this document we are describing the features that enable internationalisation in CKEditor and the tools and processes for its localisation.

Elements for Localization

Globalisation is usually related to UI features, because those are the ways software "communicate" with end users. For this to be effective, a language that the user understands must be used, matching also her/his cultural expectations.

In CKEditor the following internationalization aspects must be taken in consideration:

• Labels and text should be translatable.
• No assumptions should apply to space used by labels and text.
• The UI reading/rendering direction should be delivered in Left-to-Right (LTR) and Right-to-Left (RTL).
• Icons should be generally localizable:
  • In some cases when using letters/text - e.g. "B" for bold in English should be "F" in German (for "fett").
  • Respect UI direction (LTR vs RTL) - e.g. Undo/Redo or any icon with a LTR proposition for shadows or elements placement direction or position.
  • Cultural differences - e.g. thumbs-up is offensive in some countries.

Designing CKEditor UI components and graphical elements must take the above in consideration and smartly propose solutions that minimize the localization effort (e.g. icons that are culture neutral).

Direction

One important culture specific aspect that challenges applications is the reading direction of text. The following are the possibilities:

• Left-to-right (LTR): for example used when writing Latin scripts (e.g. English).
• Right-to-left (RTL): for example used when writing Arabic scripts (e.g. the Arabic language).
• Top-to-bottom (TTB): "available" for some ideographic languages like Japanese or Chinese, which are generally written LTR.

We're generally not intended to support TTB writing, but LTR and RTL are essential.

To be more precise, the key is the direction used by scripts used for writing in a language. This means that a language can be written in different scripts, with cases where the language can be written both LTR and RTL.

UI Direction

One important impact of the reading direction of a script is that it drives the way the brain analyses the UI of software. It does that in the exactly opposite way as it would do with LTR UIs by "scanning" the interface from right to left. Therefore if an icon or button is presented at the left in LTR, it must be reflected to the right in RTL.

The following illustrates a theoretical UI dialog in both LTR (left) and RTL (right):

Labels and Text

One of the very basic features of localisation is the ability of having text used in the application in different languages, according to configuration options or building procedures. In CKEditor this is done through a "dictionary" of strings that can be easily translated.

Language Files

Each language is represented by a single file named after the ISO 639-1 code of the language, optionally appended by the country code for a culture specific variation of that language.

The following is an example of the directory structure of language files:

/ (ckeditor-core root)
/lang/
    en.js (English)
    es.js
    it.js
    pl.js
    pt.js
    pt-br.js (Brazilian-Portuguese)        

The following is an example of how the English language file could look like in ckeditor5-core/lang/en.js:

export default {
	ok: 'OK',
	cancel: 'Cancel'
};

Default: English

The English language file represents the default source of dictionary entries for CKEditor. All other language files should be based on it.

Localization Tools

Following our experience with CKEditor 4, we'll be using the Transifex platform as the central place to accept translations. Dedicated documentation about the process involved on it as well as the necessary tools to make it happen properly will be developed and made public in a later stage.

Loading Order

Each editor instance in a page hold its own language dictionary, which is build during the editor initialisation.

Development Version

In the development version of CKEditor (ckeditor5-core), the following procedure is executed to build the dictionary:

1. The desired language is retrieved from config.lang ("lang").
2. The core/en.js file is loaded, containing the base dictionary.
3. The core/[lang].js file is loaded, if "lang" is not English and if it is available as one of the core language files.
4. The default language files for every plugin is loaded. It default to en.js but it can be different.
5. The relative [lang].js language file of every plugin is loaded, if available.

Each of the above steps overrides the language dictionary in the editor instance, which is saved into the editor.lang property. Therefore, whenever the "ok" text is needed, any part of the code can retrieve it with editor.lang.ok.

Release Version

In the release version instead, a single language file is loaded, based on the editor configuration. This file is created during the build of CKEditor by:

• Merging the results of the above procedures described for the development
• Language files from core and plugins are merged.
• As a result, missing entries are filled with the English counterparts (or the default language in case of specific plugins).

Therefore a single file is downloaded in release, containing the whole dictionary.

Graphical Elements

For all graphical elements, CKEditor assumes that they're direction independent. If direction is to be made available for any element, the API then assumes that the default version of the element is LTR and that the additional RTL version is provided.

Icons

One common graphical element used by CKEditor features is the icon. It is usually available for toolbar buttons but could be used in other contexts.

Features inform CKEditor about the existence of icons. As for globalization requirements, they should be able to inform the editor about the existence of additional variations of such icons:

• RTL version.
• Language specific version.

Graphics

Any other UI element that requires localization should make use of the CKEditor API features to load culture specific versions of such elements. The following features are available:

• In JavaScript:
  • editor.config.lang, containing the configured language code.
  • editor.lang.rtl, indicates the language direction of the editor.
• In CSS:
  • cke_rtl, a class set on UI containers indicating the language direction of the editor.

Metadata

There must be a way to inform CKEditor about localization resources available in the code, being it core, plugins or skins. For that, each subproject make use of the package.json file, by adding CKEditor metadata to it.

The following is a sample package.json with globalization metadata included (with comments, but remember that package.json cannot have comments!):

{
	...
	"ckeditor": {
		// The list of language files available.
		"lang": [ "en", "it", "pl", "pt-br" ],
		
		// The list of icons included.
		"icons": [ "align-left", "align-right", "align-center" ],
		
		// If the HDPI version is available for all icons.
		"icons-hdpi": true,
		
		// The list of icons that have a RTL version. Can be `true` for all.
		"icons-rtl": [ "align-left", "align-right" ],
		
		// The list of languages that have dedicated versions of the icons.
		"icons-lang": [ "pl" ]
	}
}

The above is reflected in the directory structure in the following way:

/ (project root)
	/lang/
		en.js
		it.js
		pl.js
		pt-br.js
	/icons/
		align-left.png
		align-right.png
		align-center.png
		/hdpi/
			align-left.png
			align-right.png
			align-center.png
		/rtl/
			align-left.png
			align-right.png
			/hdpi/
				align-left.png
				align-right.png
		/lang/
			/pl/
				align-left.png
				align-right.png
				align-center.png
				/hdpi/
					align-left.png
					align-right.png
					align-center.png

Note that both the "rtl" and "lang" icons include their respective "hdpi" version.

During the build process, all the above resources will be merged together to minimize the amount of files downloaded. For example, all icons will be merged together, creating different version of files for HDPI, RTL or language specific icons.