utils/translation-service

Clears dictionaries for test purposes.

Returns

void

Note: This method is internal, use the t() function instead to translate the editor UI parts.

This function is responsible for translating messages to the specified language. It uses translations added perviously by add (a translations dictionary and the getPluralForm() function to provide accurate translations of plural forms).

When no translation is defined in the dictionary or the dictionary does not exist, this function returns the original message string or the message plural depending on the number of elements.

translate( 'pl', { string: 'Cancel' } ); // 'Cancel'

The third optional argument is the number of elements, based on which the single form or one of the plural forms should be picked when the message is supposed to support various plural forms.

translate( 'en', { string: 'Add a space', plural: 'Add %0 spaces' }, 1 ); // 'Add a space'
translate( 'en', { string: 'Add a space', plural: 'Add %0 spaces' }, 3 ); // 'Add %0 spaces'

The message should provide an ID using the id property when the message strings are not unique and their translations should be different.

translate( 'en', { string: 'image', id: 'ADD_IMAGE' } );
translate( 'en', { string: 'image', id: 'AN_IMAGE' } );

Parameters

language : string

Target language.

message : Message

A message that will be translated.

quantity : number

The number of elements for which a plural form should be picked from the target language dictionary.

Defaults to 1

[ translations ] : Translations

Translations passed in editor config, if not provided use the global window.CKEDITOR_TRANSLATIONS.

Returns

string

Translated sentence.

If array then merge objects which are inside otherwise return given object.

Parameters

[ translations ] : ArrayOrItem<Translations>

Translations passed in editor config.

Returns

undefined | Translations

Adds translations to existing ones or overrides the existing translations. These translations will later be available for the t() function.

The translations is an object which consists of messageId: translation pairs. Note that the message ID can be either constructed from the message string or from the message ID if it was passed (this happens rarely and mostly for short messages or messages with placeholders). Since the editor displays only the message string, the message ID can be found either in the source code or in the built translations for another language.

add( 'pl', {
	'Cancel': 'Anuluj',
	'IMAGE': 'obraz', // Note that the `IMAGE` comes from the message ID, while the string can be `image`.
} );

If the message is supposed to support various plural forms, make sure to provide an array with the singular form and all plural forms:

add( 'pl', {
	'Add space': [ 'Dodaj spację', 'Dodaj %0 spacje', 'Dodaj %0 spacji' ]
} );

You should also specify the third argument (the getPluralForm() function) that will be used to determine the plural form if no language file was loaded for that language. All language files coming from CKEditor 5 sources will have this option set, so these plural form rules will be reused by other translations added to the registered languages. The getPluralForm() function can return either a Boolean or a number.

add( 'en', {
	// ... Translations.
}, n => n !== 1 );
add( 'pl', {
	// ... Translations.
}, n => n == 1 ? 0 : n % 10 >= 2 && n % 10 <= 4 && ( n % 100 < 10 || n % 100 >= 20 ) ? 1 : 2 );

All translations extend the global window.CKEDITOR_TRANSLATIONS object. An example of this object can be found below:

{
	pl: {
		dictionary: {
			'Cancel': 'Anuluj',
			'Add space': [ 'Dodaj spację', 'Dodaj %0 spacje', 'Dodaj %0 spacji' ]
		},
		// A function that returns the plural form index.
		getPluralForm: n => n == 1 ? 0 : n % 10 >= 2 && n % 10 <= 4 && ( n % 100 < 10 || n % 100 >= 20 ) ? 1 : 2 );
	}
	// Other languages.
	}

If you cannot import { this function } from this module (e.g. because you use a CKEditor 5 build), you can still add translations by extending the global window.CKEDITOR_TRANSLATIONS object by using a function like the one below:

function addTranslations( language, translations, getPluralForm ) {
	if ( !global.window.CKEDITOR_TRANSLATIONS ) {
		global.window.CKEDITOR_TRANSLATIONS = {};
	}

	if ( !global.window.CKEDITOR_TRANSLATIONS[ language ] ) {
		global.window.CKEDITOR_TRANSLATIONS[ language ] = {};
	}

	const languageTranslations = global.window.CKEDITOR_TRANSLATIONS[ language ];

	languageTranslations.dictionary = languageTranslations.dictionary || {};
	languageTranslations.getPluralForm = getPluralForm || languageTranslations.getPluralForm;

	// Extend the dictionary for the given language.
	Object.assign( languageTranslations.dictionary, translations );
}

Parameters

language : string

Target language.

translations : object

An object with translations which will be added to the dictionary. For each message ID the value should be either a translation or an array of translations if the message should support plural forms.

Properties

translations.[messageId: string] : string | readonly Array<string>

[ getPluralForm ] : ( n: number ) => number

A function that returns the plural form index (a number).

Returns

void