# utils/translation-service

module

<a id="interfaces">

## Interfaces

<a id="interface-Message">

### `Message`

<a id="functions">

## Functions

<a id="function-_clear">

### `_clear() → void` _(internal)_

Clears dictionaries for test purposes.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/translation-service.ts#L221)

#### Returns

* `void`

<a id="function-_translate">

### `_translate( language, message, quantity, translations? ) → string` _(internal)_

**Note:** This method is internal, use [the `t()` function](module_utils_locale-Locale.md#member-t) 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`](#function-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.

```typescript
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.

```typescript
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.

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/translation-service.ts#L165)

#### 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.

<a id="function-_unifyTranslations">

### `_unifyTranslations( translations? ) → Translations | undefined` _(internal)_

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/translation-service.ts#L233)

#### Parameters

* `translations?: ArrayOrItem<Translations>`

  Translations passed in editor config.

#### Returns

* `Translations | undefined`

<a id="function-add">

### `add( language, translations = { translations.[messageId: string] }, getPluralForm? ) → void`

Adds translations to existing ones or overrides the existing translations. These translations will later be available for the [`t()`](module_utils_locale-Locale.md#member-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.

```typescript
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:

```typescript
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.

```typescript
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:

```typescript
{
	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:

```typescript
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 );
}
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/translation-service.ts#L110)

#### 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`

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)