CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Module

utils/translation-service

@ckeditor/ckeditor5-utils/src/translation-service

module

Filtering

Type Definitions

  • Message

    The internationalization message interface. A message that implements this interface can be passed to the t() function to be translated to the target UI language.

    See source

Functions

  • _clear()

    protected

    Clears dictionaries for test purposes.

    See source

  • _translate( language, message, [ quantity ] ) → String

    protected

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

    See source

    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.

    Returns

    String

    Translated sentence.

  • add( language, translations, getPluralForm )

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

    See source

    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
	}
	// 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 ( !window.CKEDITOR_TRANSLATIONS ) {
		window.CKEDITOR_TRANSLATIONS = {};
	}
	if ( !window.CKEDITOR_TRANSLATIONS[ language ] ) {
		window.CKEDITOR_TRANSLATIONS[ language ] = {};
	}

	const languageTranslations = 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.<String, *>

    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.

    getPluralForm : function

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