Настройка русской локализации

Любая интерфейсная библиотека предназначена для создания визуальных компонентов пользовательского интерфейса. В большинстве случаев такие библиотеки поставляются с английскими строками интерфейса по умолчанию. Это касается:

  • текста кнопок;
  • подписей элементов управления;
  • системных сообщений;
  • названий месяцев и дней недели;
  • подсказок и уведомлений;
  • текста пагинации, фильтров и таблиц.

В приложениях, ориентированных на русскоязычную аудиторию, использование английских строк ухудшает пользовательский опыт. Для решения этой задачи используется локализация (localization) — механизм перевода интерфейса на нужный язык.

В библиотеке Ant Design локализация реализована централизованно через компонент ConfigProvider, который позволяет:

  • переключать язык интерфейса;
  • настраивать форматирование дат;
  • изменять тексты стандартных компонентов;
  • синхронизировать локаль с библиотекой работы с датами.

Механизм локализации в Ant Design

Ant Design содержит встроенные файлы локалей для большого количества языков. Каждый файл представляет собой объект конфигурации, который включает переводы строк интерфейса для компонентов.

Локализация применяется глобально через компонент ConfigProvider. Этот компонент оборачивает всё приложение и передаёт настройки локали всем компонентам внутри.

Стандартная структура выглядит следующим образом:

import { ConfigProvider } from 'antd'
import ruRU from 'antd/locale/ru_RU'

function App() {
  return (
    <ConfigProvider locale={ruRU}>
      <Application />
    </ConfigProvider>
  )
}

После применения этой настройки компоненты Ant Design автоматически начинают использовать русские строки интерфейса.

Подключение русской локали

Файл русской локализации поставляется вместе с библиотекой и находится по пути:

antd/locale/ru_RU

Подключение производится через импорт:

import ruRU from 'antd/locale/ru_RU'

Этот объект содержит переводы для следующих компонентов:

  • Pagination
  • DatePicker
  • TimePicker
  • Calendar
  • Table
  • Modal
  • Popconfirm
  • Transfer
  • Upload
  • Empty
  • Form

После передачи объекта в ConfigProvider перевод применяется автоматически.

Пример полной конфигурации приложения

Типичная структура приложения с локализацией выглядит следующим образом:

import React from 'react'
import ReactDOM from 'react-dom/client'
import { ConfigProvider } from 'antd'
import ruRU from 'antd/locale/ru_RU'
import App from './App'

const root = ReactDOM.createRoot(document.getElementById('root'))

root.render(
  <ConfigProvider locale={ruRU}>
    <App />
  </ConfigProvider>
)

После этого:

  • календарь отображает русские месяцы;
  • пагинация использует русские подписи;
  • модальные окна получают русские кнопки;
  • таблицы используют русские тексты фильтров.

Локализация компонентов дат

Компоненты, связанные с датами, требуют дополнительной настройки. В Ant Design используется библиотека Day.js (начиная с версии Ant Design 5) для работы с датами.

Даже при подключении ru_RU календарь может продолжать показывать английские названия месяцев. Причина заключается в том, что библиотека дат должна также быть переключена на русскую локаль.

Для этого необходимо импортировать русскую локаль Day.js.

import dayjs from 'dayjs'
import 'dayjs/locale/ru'

dayjs.locale('ru')

После этого:

  • названия месяцев отображаются по-русски;
  • дни недели переводятся;
  • форматирование дат соответствует русской локали.

Полная конфигурация:

import { ConfigProvider } from 'antd'
import ruRU from 'antd/locale/ru_RU'
import dayjs from 'dayjs'
import 'dayjs/locale/ru'

dayjs.locale('ru')

function App() {
  return (
    <ConfigProvider locale={ruRU}>
      <Application />
    </ConfigProvider>
  )
}

Локализация DatePicker

Компонент выбора даты автоматически использует строки локали Ant Design и форматирование Day.js.

Пример использования:

import { DatePicker } from 'antd'

function Example() {
  return <DatePicker />
}

После настройки локализации интерфейс будет выглядеть следующим образом:

  • месяцы: январь, февраль, март;
  • дни недели: пн, вт, ср;
  • кнопки: “Сегодня”, “ОК”.

Локализация Pagination

Компонент пагинации также содержит текстовые элементы, которые переводятся через локаль.

Пример компонента:

import { Pagination } from 'antd'

function Example() {
  return (
    <Pagination
      total={500}
      pageSize={10}
    />
  )
}

При активной русской локали появляются следующие тексты:

  • «Страница»
  • «Перейти»
  • «элементов»

Эти строки автоматически подставляются из объекта ru_RU.

Локализация таблиц (Table)

Компонент таблицы содержит несколько встроенных текстовых элементов:

  • текст фильтров;
  • кнопки подтверждения;
  • текст пустой таблицы;
  • подсказки сортировки.

Пример таблицы:

import { Table } from 'antd'

const columns = [
  {
    title: 'Имя',
    dataIndex: 'name'
  }
]

const data = [
  { key: 1, name: 'Иван' }
]

function Example() {
  return <Table columns={columns} dataSource={data} />
}

При использовании ru_RU автоматически переводятся:

  • кнопки фильтров;
  • текст “Нет данных”;
  • элементы интерфейса сортировки.

Локализация модальных окон

Компоненты Modal и Popconfirm имеют системные кнопки:

  • OK
  • Cancel

После подключения русской локали они заменяются на:

  • «ОК»
  • «Отмена»

Пример модального окна:

import { Modal, Button } from 'antd'
import { useState } from 'react'

function Example() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <Button onCl ick={() => setOpen(true)}>Открыть</Button>

      <Modal
        open={open}
        onCan cel={() => setOpen(false)}
        onOk={() => setOpen(false)}
      >
        Содержимое окна
      </Modal>
    </>
  )
}

Тексты кнопок автоматически берутся из локали.

Локализация сообщений Form

Компонент формы содержит стандартные сообщения валидации:

  • обязательное поле;
  • неверный формат;
  • слишком короткое значение.

Эти сообщения также переводятся через локаль.

Пример:

import { Form, Input } from 'antd'

function Example() {
  return (
    <Form>
      <Form.Item
        label="Имя"
        name="name"
        rules={[{ required: true }]}
      >
        <Input />
      </Form.Item>
    </Form>
  )
}

При пустом поле отображается сообщение:

Пожалуйста, введите имя

Частичная локализация компонентов

Иногда требуется изменить только некоторые строки интерфейса, не меняя всю локаль. Это возможно через модификацию объекта локализации.

Пример изменения текста пустого состояния:

import ruRU from 'antd/locale/ru_RU'

const customLocale = {
  ...ruRU,
  Empty: {
    description: 'Нет записей'
  }
}

Использование:

<ConfigProvider locale={customLocale}>
  <App />
</ConfigProvider>

Динамическое переключение языка

В некоторых приложениях требуется переключать язык интерфейса во время работы. Для этого локаль хранится в состоянии приложения.

Пример:

import { useState } from 'react'
import { ConfigProvider } from 'antd'
import ruRU from 'antd/locale/ru_RU'
import enUS from 'antd/locale/en_US'

function App() {
  const [locale, setLocale] = useState(ruRU)

  return (
    <ConfigProvider locale={locale}>
      <Application changeLocale={setLocale} />
    </ConfigProvider>
  )
}

Переключение:

setLocale(enUS)

или

setLocale(ruRU)

Все компоненты интерфейса обновят язык автоматически.

Типичные проблемы локализации

Календарь остаётся английским

Причина — не подключена локаль Day.js.

Решение:

import 'dayjs/locale/ru'
dayjs.locale('ru')

Русский перевод применился не ко всем компонентам

Причина — компонент находится вне ConfigProvider.

Решение — убедиться, что всё приложение обёрнуто в провайдер:

<ConfigProvider locale={ruRU}>
  <App />
</ConfigProvider>

Неправильный формат даты

Формат дат задаётся отдельно:

<DatePicker format="DD.MM.YYYY" />

Архитектурные рекомендации

При использовании локализации в крупных проектах рекомендуется:

1. Создать отдельный модуль локализации

src/i18n/antdLocale.js
import ruRU from 'antd/locale/ru_RU'

export default ruRU

2. Централизовать настройку Day.js

src/i18n/dayjs.js
import dayjs from 'dayjs'
import 'dayjs/locale/ru'

dayjs.locale('ru')

export default dayjs

3. Хранить текущий язык в глобальном состоянии

Это может быть:

  • React Context
  • Redux
  • Zustand

Такая архитектура позволяет:

  • легко добавлять новые языки;
  • переключать локализацию без перезапуска приложения;
  • централизованно управлять переводами.
Оглавление