Naive UI I18N

Naive UI Internationalization (i18n)

Configure internationalization in Naive UI to support multiple languages and customize component locales.

When to Use

Use this skill when you need to:

• Set up multi-language support in your application
• Change the language of Naive UI components
• Customize existing locale strings
• Add support for new languages

Prerequisites

• Basic understanding of Naive UI setup
• Vue 3 Composition API knowledge
• Understanding of internationalization concepts

Basic Usage

Setting Up Locale

Use n-config-provider to set the locale for all descendant components:

<template>
  <n-config-provider :locale="enUS" :date-locale="dateEnUS">
    <App />
  </n-config-provider>
</template>

<script setup>
import { NConfigProvider } from 'naive-ui'
import { enUS, dateEnUS } from 'naive-ui'
</script>

Switching Languages Dynamically

<template>
  <n-config-provider :locale="locale" :date-locale="dateLocale">
    <n-space vertical>
      <n-select 
        v-model:value="currentLang" 
        :options="langOptions"
        @update:value="handleLangChange"
      />
      <n-date-picker type="date" />
      <n-pagination :page-count="10" />
    </n-space>
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { enUS, dateEnUS, zhCN, dateZhCN } from 'naive-ui'

const currentLang = ref('en')
const locale = ref(enUS)
const dateLocale = ref(dateEnUS)

const langOptions = [
  { label: 'English', value: 'en' },
  { label: '中文', value: 'zh' }
]

const handleLangChange = (lang) => {
  if (lang === 'en') {
    locale.value = enUS
    dateLocale.value = dateEnUS
  } else if (lang === 'zh') {
    locale.value = zhCN
    dateLocale.value = dateZhCN
  }
}
</script>

Supported Languages

Naive UI supports the following languages (PRs are welcome for new languages):

Customizing Locales

Using createLocale

Customize existing locale strings using createLocale:

<template>
  <n-config-provider :locale="customLocale" :date-locale="dateEnUS">
    <n-input placeholder="This should show 'Okay'" />
  </n-config-provider>
</template>

<script setup>
import { NConfigProvider, createLocale, enUS, dateEnUS } from 'naive-ui'

const customLocale = createLocale(
  {
    Input: {
      placeholder: 'Okay'
    }
  },
  enUS
)
</script>

Full Locale Customization Example

<template>
  <n-config-provider :locale="customLocale">
    <n-space vertical>
      <n-input :placeholder="customLocale.Input.placeholder" />
      <n-empty :description="customLocale.Empty.description" />
      <n-pagination :page-count="5" />
    </n-space>
  </n-config-provider>
</template>

<script setup>
import { createLocale, enUS } from 'naive-ui'

const customLocale = createLocale(
  {
    Input: {
      placeholder: 'Enter text here...'
    },
    Empty: {
      description: 'No data available'
    },
    Pagination: {
      goto: 'Go to',
      pagesize: '/page',
      total: 'Total {count} items',
      pageSeparator: 'of',
      page: 'Page',
      prev: 'Previous',
      next: 'Next',
      prevPage: 'Previous page',
      nextPage: 'Next page',
      prev: 'Prev',
      next: 'Next'
    }
  },
  enUS
)
</script>

API Reference

n-config-provider Locale Props

createLocale Function

function createLocale(
  overrides: PartialLocale,
  baseLocale: Locale
): Locale

Creates a new locale by merging custom overrides with a base locale.

Common Patterns

Persistent Language Selection

<template>
  <n-config-provider :locale="locale" :date-locale="dateLocale">
    <n-select 
      v-model:value="currentLang" 
      :options="langOptions"
      style="width: 200px; margin-bottom: 20px;"
    />
    <router-view />
  </n-config-provider>
</template>

<script setup>
import { ref, onMounted, watch } from 'vue'
import { enUS, dateEnUS, zhCN, dateZhCN, jaJP, dateJaJP } from 'naive-ui'

const langMap = {
  en: { locale: enUS, dateLocale: dateEnUS },
  zh: { locale: zhCN, dateLocale: dateZhCN },
  ja: { locale: jaJP, dateLocale: dateJaJP }
}

const currentLang = ref('en')
const locale = ref(enUS)
const dateLocale = ref(dateEnUS)

const langOptions = [
  { label: 'English', value: 'en' },
  { label: '中文', value: 'zh' },
  { label: '日本語', value: 'ja' }
]

watch(currentLang, (newLang) => {
  const config = langMap[newLang]
  if (config) {
    locale.value = config.locale
    dateLocale.value = config.dateLocale
    localStorage.setItem('app-language', newLang)
  }
})

onMounted(() => {
  const savedLang = localStorage.getItem('app-language') || 'en'
  currentLang.value = savedLang
})
</script>

Integration with vue-i18n

<template>
  <n-config-provider :locale="naiveLocale" :date-locale="naiveDateLocale">
    <App />
  </n-config-provider>
</template>

<script setup>
import { computed } from 'vue'
import { useI18n } from 'vue-i18n'
import { enUS, dateEnUS, zhCN, dateZhCN } from 'naive-ui'

const { locale } = useI18n()

const naiveLocale = computed(() => {
  return locale.value === 'zh' ? zhCN : enUS
})

const naiveDateLocale = computed(() => {
  return locale.value === 'zh' ? dateZhCN : dateEnUS
})
</script>

Best Practices

1. Persist Language Preference: Store the user's language choice in localStorage
2. Separate Date Locale: Always set both locale and date-locale for consistent formatting
3. Use Base Locale: When customizing, always extend from an existing locale using createLocale
4. Test All Languages: Verify your application works correctly with all supported languages
5. Consider RTL: Some languages (Arabic, Persian) require right-to-left layout support
6. Sync with App i18n: Keep Naive UI locale in sync with your application's i18n system

Component-Specific Locale Keys

Different components have their own locale keys that can be customized:

const customLocale = createLocale({
  // Button
  Button: {
    loadingText: 'Loading...'
  },
  // Input
  Input: {
    placeholder: 'Please input',
    clear: 'Clear'
  },
  // DatePicker
  DatePicker: {
    placeholder: 'Select date',
    clear: 'Clear',
    confirm: 'OK',
    now: 'Now'
  },
  // Table
  DataTable: {
    check: 'Check',
    clear: 'Clear',
    clearFilters: 'Clear filters',
    clearSorter: 'Clear sorter'
  },
  // Transfer
  Transfer: {
    source: 'Source',
    target: 'Target',
    searchPlaceholder: 'Search',
    clear: 'Clear'
  },
  // Upload
  Upload: {
    draggerClick: 'Click to upload',
    draggerDrag: 'Drag files here',
    fileDrag: 'Drag files here',
    accept: 'Accept: {accept}',
    upload: 'Upload',
    retry: 'Retry',
    remove: 'Remove',
    cancel: 'Cancel'
  }
}, enUS)