Mplan
02d64bf206
Add 12 Naive UI skill modules (components, dark mode, design tokens, i18n, SSR, theming, quickstart) and web-design-reviewer skill.
353 lines
8.6 KiB
Markdown
353 lines
8.6 KiB
Markdown
---
|
|
name: naive-ui-i18n
|
|
description: Configure internationalization (i18n) in Naive UI with support for multiple languages and custom locales
|
|
metadata:
|
|
author: jiaiyan
|
|
version: 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:
|
|
|
|
```vue
|
|
<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
|
|
|
|
```vue
|
|
<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`:
|
|
|
|
```vue
|
|
<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
|
|
|
|
```vue
|
|
<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
|
|
|
|
```typescript
|
|
function createLocale(
|
|
overrides: PartialLocale,
|
|
baseLocale: Locale
|
|
): Locale
|
|
```
|
|
|
|
Creates a new locale by merging custom overrides with a base locale.
|
|
|
|
## Common Patterns
|
|
|
|
### Persistent Language Selection
|
|
|
|
```vue
|
|
<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
|
|
|
|
```vue
|
|
<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:
|
|
|
|
```javascript
|
|
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)
|
|
```
|