Кастомные локали

Библиотека Naive UI предоставляет мощный механизм для интернационализации компонентов через систему локалей. Каждый компонент имеет встроенные тексты по умолчанию, но их можно заменять на кастомные значения для поддержки различных языков, форматов даты и чисел, а также пользовательских сообщений.

Подключение и использование локалей

Naive UI использует объект locale для передачи локализованных строк в компоненты. Для глобальной установки локали используется провайдер n-config-provider, который обеспечивает единый источник локалей для всех дочерних компонентов.

import { createApp } from 'vue'
import { create, NConfigProvider, enUS, ruRU } from 'naive-ui'
import App from './App.vue'

const naive = create()

const app = createApp(App)
app.use(naive)

app.mount('#app')
<NConfigProvider :locale="customLocale">
  <NButton>Пример кнопки</NButton>
</NConfigProvider>

Здесь customLocale — это объект, определяющий пользовательские строки.

Структура объекта локали

Локаль в Naive UI — это объект с набором ключей, соответствующих компонентам. Каждый ключ содержит подполя с текстами компонентов:

const customLocale = {
  datePicker: {
    placeholder: 'Выберите дату',
    rangePlaceholder: ['Начало', 'Конец'],
    shortcuts: {
      today: 'Сегодня',
      yesterday: 'Вчера',
      last7Days: 'Последние 7 дней'
    }
  },
  pagination: {
    goto: 'Перейти на',
    page: 'страницу',
    itemsPerPage: 'элементов на страницу'
  },
  dialog: {
    positiveText: 'Ок',
    negativeText: 'Отмена'
  }
}

Ключевые моменты структуры:

  • Каждому компоненту соответствует отдельный объект (datePicker, pagination, dialog и др.).
  • Подполя содержат строки для всех отображаемых текстов компонента.
  • Для компонентов с динамическим содержимым допустимы функции, возвращающие строки с параметрами.

Локализация компонентов с функциями

Некоторые компоненты требуют локализации с динамическими значениями. Например, pagination может использовать функцию для формирования текста:

const customLocale = {
  pagination: {
    total: (count) => `Всего элементов: ${count}`,
    goto: 'Перейти на',
    page: 'страницу'
  }
}

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

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

Naive UI поддерживает динамическое изменение локалей через реактивный объект. Используя Vue 3 Composition API:

import { ref } from 'vue'
import { ruRU, enUS } from 'naive-ui'

const currentLocale = ref(ruRU)

function switchLocale(lang) {
  currentLocale.value = lang === 'ru' ? ruRU : enUS
}
<NConfigProvider :locale="currentLocale">
  <NButton @click="switchLocale('en')">Сменить язык</NButton>
</NConfigProvider>

Таким образом, все дочерние компоненты автоматически подхватывают новую локаль без перезагрузки приложения.

Модификация существующих локалей

Можно не создавать полностью кастомную локаль, а модифицировать существующую. Для этого используется оператор расширения объекта:

import { ruRU } from 'naive-ui'

const customLocale = {
  ...ruRU,
  button: {
    ...ruRU.button,
    loading: 'Загрузка...'
  }
}

Такой подход позволяет менять только необходимые строки, сохраняя все остальные из стандартной локали.

Локализация компонентов, использующих message и notification

Для компонентов уведомлений и сообщений также можно задавать локали:

const customLocale = {
  message: {
    info: 'Информация',
    success: 'Успешно',
    warning: 'Внимание',
    error: 'Ошибка'
  },
  notification: {
    close: 'Закрыть'
  }
}

Эти строки будут применяться при вызове методов message.info(), message.success() и т.д.

Советы по организации кастомных локалей

  • Делать локаль реактивной: использование ref или reactive обеспечивает мгновенное обновление текста во всех компонентах.
  • Использовать расширение стандартных локалей: проще модифицировать существующие объекты (enUS, ruRU), чем писать с нуля.
  • Группировать строки по компонентам: это облегчает поддержку и расширение локали.
  • Использовать функции для динамических значений: для чисел, дат и текста с параметрами.

Пример полной кастомной локали

import { reactive } from 'vue'

export const customLocale = reactive({
  datePicker: {
    placeholder: 'Выберите дату',
    rangePlaceholder: ['Начало', 'Конец'],
    shortcuts: {
      today: 'Сегодня',
      yesterday: 'Вчера',
      last7Days: 'Последние 7 дней'
    }
  },
  pagination: {
    total: (count) => `Всего элементов: ${count}`,
    goto: 'Перейти на',
    page: 'страницу',
    itemsPerPage: 'элементов на страницу'
  },
  dialog: {
    positiveText: 'Подтвердить',
    negativeText: 'Отмена'
  },
  message: {
    info: 'Информация',
    success: 'Успешно',
    warning: 'Внимание',
    error: 'Ошибка'
  },
  notification: {
    close: 'Закрыть'
  },
  button: {
    loading: 'Загрузка...'
  }
})

Такой подход позволяет централизованно управлять всеми текстами интерфейса и обеспечивать единый стиль локализации в приложении на Naive UI.

Оглавление