opencloud/.agents/skills/naive-ui-i18n/SKILL.md

name, description, metadata

name	description	metadata
naive-ui-i18n	Configure internationalization (i18n) in Naive UI with support for multiple languages and custom locales	author version jiaiyan 1.0.0

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):

Language	Config	Date Config	Version
Arabic (العربية)	arDZ	dateArDZ	2.34.0
Azerbaijani (Azərbaycanca)	azAZ	dateAzAZ	2.39.0
Czech (Czechia)	csCZ	dateCsCz	2.38.2
Danish (Denmark)	daDK	dateDaDK	2.43.0
German (Germany)	deDE	dateDeDE	-
English (British)	enGB	dateEnGB	2.25.1
English	enUS	dateEnUS	-
Esperanto	eo	dateEo	2.25.2
Spanish (Argentina)	esAR	dateEsAR	2.24.2
Estonian	etEE	dateEtEE	2.38.0
Persian	faIR	dateFaIR	2.34.4
French	frFR	dateFrFR	-
Bahasa Indonesia	idID	dateIdID	-
Italiano	itIT	dateItIT	2.24.2
Japanese	jaJP	dateJaJP	-
Khmer (Cambodia)	kmKH	dateKmKH	2.41.0
Korean (South Korea)	koKR	dateKoKR	2.28.1
Norwegian Bokmål (Norway)	nbNO	dateNbNO	-
Dutch (Netherlands)	nlNL	dateNlNL	2.29.0
Polish (Poland)	plPL	datePlPL	2.25.2
Portuguese (Brazil)	ptBR	datePtBR	2.28.1
Russian	ruRU	dateRuRU	-
Slovak	skSK	dateSkSK	2.25.3
Swedish	svSE	dateSvSE	2.35.0
Thai (Thailand)	thTH	dateThTH	2.27.0
Turkish	trTR	dateTrTR	2.34.0
Uyghur (China)	ugCN	dateUgCN	-
Ukrainian	ukUA	dateUkUA	-
Uzbek (Uzbekistan)	uzUZ	dateUzUZ	2.39.0
Vietnamese (Vietnam)	viVN	dateViVN	2.30.7
Chinese (Simplified)	zhCN	dateZhCN	-
Chinese (Traditional)	zhTW	dateZhTW	-

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

Property	Type	Default	Description
locale	object	enUS	Locale configuration for components
date-locale	object	dateEnUS	Date format locale configuration

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)