# Интернационализация

- Human documentation: [https://docs.univer.ai/ru-RU/guides/sheets/getting-started/i18n](https://docs.univer.ai/ru-RU/guides/sheets/getting-started/i18n)

- Agent Markdown: [https://docs.univer.ai/ru-RU/guides/sheets/getting-started/i18n.md](https://docs.univer.ai/ru-RU/guides/sheets/getting-started/i18n.md)

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

- Source: [sheets/getting-started/i18n.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/getting-started/i18n.ru-RU.mdx)

---

## Язык интерфейса

`locale` выбирает языковой пакет меню, подсказок, диалогов и других переводимых элементов интерфейса. `locales` регистрирует пакеты, но не выбирает язык. Настройка общая для всех документов экземпляра Univer. Используйте значения `LocaleType`, например `LocaleType.EN_US`.

* **Все продукты: интерфейс**: `locale` меняет переводы меню, подсказок, диалогов и подписей плагинов. Пользовательский текст и имена существующих документов не меняются.
* **Sheets: форматы и формулы**: Для отображения чисел/дат сначала используется переопределённая locale числового формата, затем `locale` снимка книги, затем `locale` экземпляра. `region` не заменяет эти настройки. `DOLLAR`, денежные форматы результатов финансовых функций и нормализация ввода CJK по-прежнему используют `locale`.
* **Docs: статистика**: `locale` используется для разбиения текста на слова и подсчёта.

### Смена языка во время работы

Перед сменой языка загрузите пакеты всех установленных плагинов или пресетов. `loadLocales()` объединяет переводы, не меняя язык; `setLocale()` выбирает язык, но ничего не скачивает. Вместо отсутствующих переводов отображаются ключи. Пример загружает общий пакет UI; в тот же вызов добавьте пакеты целевого языка остальных установленных плагинов.

```typescript
import { LocaleType, mergeLocales } from '@univerjs/core'
import UIEnUS from '@univerjs/ui/locale/en-US'

univerAPI.loadLocales(LocaleType.EN_US, mergeLocales(UIEnUS))
univerAPI.setLocale(LocaleType.EN_US)

console.log(univerAPI.getCurrentLocale()) // enUS
```

### Регистрация языковых пакетов в режиме пресетов

В пакеты пресетов уже включены языковые пакеты соответствующих плагинов — их нужно только импортировать из пресета.

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US' // [!code highlight]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS, // [!code highlight]
    ),
  },
  presets: [UniverSheetsCorePreset()],
})
```

### Регистрация языковых пакетов в режиме плагинов

Чтобы зарегистрировать языковые пакеты в режиме плагинов, импортируйте нужные пакеты из предоставляющих их плагинов, объедините в один объект и передайте его экземпляру `Univer`. Пример:

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import DesignEnUS from '@univerjs/design/locale/en-US' // [!code highlight]
import SheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US' // [!code highlight]
import UIEnUS from '@univerjs/ui/locale/en-US' // [!code highlight]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      DesignEnUS, // [!code highlight]
      UIEnUS, // [!code highlight]
      SheetsUIEnUS, // [!code highlight]
    ),
  },
})
```

> [!WARNING: Внимание]
> Языковые пакеты доступны не для всех плагинов. Информация об их наличии приводится в документации каждой функции.

### Объединение языковых пакетов

Метод `mergeLocales` объединяет языковые пакеты нескольких плагинов или пресетов в единый объект языкового пакета. Использовать его можно следующим образом:

#### Режим пресетов

```typescript
import { mergeLocales } from '@univerjs/presets'

// You can pass multiple language pack objects to merge
const locales = mergeLocales(
  plugin1Locales,
  plugin2Locales,
  presetLocales,
)
// You can also pass an array of language pack objects
const locales = mergeLocales([
  plugin1Locales,
  plugin2Locales,
  presetLocales,
])
```

#### Режим плагинов

```typescript
import { mergeLocales } from '@univerjs/core'

// You can pass multiple language pack objects to merge
const locales = mergeLocales(
  plugin1Locales,
  plugin2Locales,
  presetLocales,
)
// You can also pass an array of language pack objects
const locales = mergeLocales([
  plugin1Locales,
  plugin2Locales,
  presetLocales,
])
```

### Пользовательские языковые пакеты

Univer также поддерживает пользовательские языковые пакеты. Вы можете сформировать объект языкового пакета в соответствии со своими требованиями и передать его экземпляру `Univer`. Языковые пакеты пресетов обычно находятся в каталоге `<rootDir>/packages/<PLUGIN_NAME>/locale`.

```typescript
import { LocaleType, Univer } from '@univerjs/core'

const univer = new Univer({
  locale: LocaleType.JA_JP,
  locales: {
    [LocaleType.JA_JP]: {
      ui: {
        shortcut: {
          undo: '元に戻す',
          redo: 'やり直す',
        },
      },
    },
  },
})
```

### Участие в переводе

В настоящее время Univer включает следующие языковые пакеты:

* `zh-CN`: упрощённый китайский
* `en-US`: английский
* `zh-TW`: традиционный китайский
* `zh-HK`: традиционный китайский (Гонконг)
* `ru-RU`: русский
* `vi-VN`: вьетнамский
* `fa-IR`: персидский
* `fr-FR`: французский
* `ja-JP`: японский
* `ko-KR`: корейский
* `es-ES`: испанский
* `ca-ES`: каталонский
* `sk-SK`: словацкий
* `ar-SA`: арабский
* `de-DE`: немецкий
* `id-ID`: индонезийский
* `it-IT`: итальянский
* `pl-PL`: польский
* `pt-BR`: португальский (Бразилия)

Univer — открытый и инклюзивный проект. Мы приглашаем разработчиков со всего мира добавлять и улучшать локализации Univer.

## Региональные настройки

`region` задаёт региональные правила для соответствующих функций. Настройка общая для всех документов экземпляра Univer.

Для обоих параметров используйте `LocaleType`: например, `LocaleType.EN_US` имеет значение `enUS`, а `en-US` — это имя файла языкового пакета / тег BCP 47. Не передавайте коды стран вроде `US` или `SG` в `region`. Если интерфейс использует другой язык, загружать языковой пакет региона не нужно.

Без явного значения `region` следует за `locale`, включая последующие вызовы `setLocale()`. Установка `region` при инициализации или вызов `setRegion()` прекращает это поведение. При последующей смене языка выбранный регион сохраняется. Публичного API для возврата к автоматическому следованию нет; задавайте оба значения, если они должны меняться вместе.

Добавьте `region: LocaleType.DE_DE` рядом с `locale` в `createUniver()` или `new Univer()`, чтобы сохранить язык интерфейса и использовать региональные правила Германии.

```typescript
import { LocaleType } from '@univerjs/core'

univerAPI.setRegion(LocaleType.DE_DE)
univerAPI.setLocale(LocaleType.EN_US)

console.log(univerAPI.getCurrentRegion()) // deDE
```

В этом примере интерфейс переключается на английский, а регион остаётся немецким. `getCurrentLocale()` и `getCurrentRegion()` возвращают действующие идентификаторы. Для совместного изменения вызовите оба setter с одним значением `LocaleType`.

* **Sheets: денежные форматы**: `region` определяет значок валюты, варианты и предпросмотр денежных/финансовых форматов и формат, применяемый командой валюты. Смена региона не переписывает форматы существующих ячеек и не конвертирует суммы.
* **Docs: статистика**: `region` форматирует числа в диалоге статистики и строке состояния (например, разделители групп разрядов), не меняя правила подсчёта.
* **Ветки комментариев, если включены**: `region` определяет формат даты/времени с 24-часовым представлением и латинскими цифрами. `locale` задаёт язык интерфейса комментариев. Сохранённые метки времени не меняются; `region` не задаёт часовой пояс.
* **Boards, Slides, Bases, PDFs**: `locale` управляет переводом интерфейса. `region` доступен общим подключённым функциям, например веткам комментариев, но не переформатирует автоматически текст досок/слайдов, поля Base или содержимое PDF.

## Расположение справа налево

> [!WARNING: Внимание]
> В настоящее время RTL поддерживается только на уровне UI. Уровень рендеринга не поддерживает RTL.

Направление интерфейса задаётся отдельно: через `direction` при инициализации или `univerAPI.setDirection('rtl')` / `setDirection('ltr')`. Изменение только `locale` или `region` не меняет направление.

```typescript
univerAPI.setDirection('rtl')
```