element-plus-i18n

name	element-plus-i18n
description	Configures internationalization and localization for Element Plus components. Invoke when user needs to change language, add custom translations, or configure locale settings.
metadata	{"author":"jiaiyan","version":"1.0.0"}

Element Plus Internationalization

This skill provides comprehensive guidance for configuring internationalization (i18n) in Element Plus applications.

When to Invoke

Invoke this skill when:

• User wants to change the default language
• User needs to configure multiple languages
• User asks about date/time localization
• User wants to add custom translations
• User needs to switch languages dynamically

Default Language

Element Plus components use English by default. To use other languages, you need to configure the locale.

Configuration Methods

1. Global Configuration

Configure the locale when registering Element Plus:

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus, {
  locale: zhCn,
})

2. ConfigProvider Component

Use el-config-provider for dynamic locale switching:

<template>
  <el-config-provider :locale="locale">
    <app />
  </el-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { ElConfigProvider } from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import en from 'element-plus/es/locale/lang/en'

const locale = ref(zhCn)

const switchLanguage = (lang) => {
  locale.value = lang === 'zh' ? zhCn : en
}
</script>

3. CDN Usage

For CDN-based projects:

<script src="//unpkg.com/element-plus/dist/locale/zh-cn"></script>
<script>
  app.use(ElementPlus, {
    locale: ElementPlusLocaleZhCn,
  })
</script>

Date and Time Localization

Element Plus uses Day.js for date/time management in components like DatePicker. You must import Day.js locale separately:

import 'dayjs/locale/zh-cn'

Complete Example with DatePicker

<template>
  <el-config-provider :locale="locale">
    <el-date-picker
      v-model="date"
      type="date"
      placeholder="Pick a day"
    />
  </el-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import 'dayjs/locale/zh-cn'

const locale = ref(zhCn)
const date = ref('')
</script>

Supported Languages

Element Plus supports 50+ languages. Here's a partial list:

Language	Code	Import Path
Simplified Chinese	zh-cn	element-plus/es/locale/lang/zh-cn
American English	en	element-plus/es/locale/lang/en
Traditional Chinese	zh-tw	element-plus/es/locale/lang/zh-tw
Hong Kong Chinese	zh-hk	element-plus/es/locale/lang/zh-hk
Japanese	ja	element-plus/es/locale/lang/ja
Korean	ko	element-plus/es/locale/lang/ko
German	de	element-plus/es/locale/lang/de
French	fr	element-plus/es/locale/lang/fr
Spanish	es	element-plus/es/locale/lang/es
Portuguese	pt	element-plus/es/locale/lang/pt
Russian	ru	element-plus/es/locale/lang/ru
Arabic	ar	element-plus/es/locale/lang/ar
Thai	th	element-plus/es/locale/lang/th
Vietnamese	vi	element-plus/es/locale/lang/vi

Full list available at: GitHub - Element Plus Locale

Dynamic Language Switching

Complete Example

<template>
  <div>
    <el-select v-model="currentLang" @change="changeLanguage">
      <el-option label="简体中文" value="zh-cn" />
      <el-option label="English" value="en" />
      <el-option label="日本語" value="ja" />
    </el-select>

    <el-config-provider :locale="locale">
      <el-date-picker
        v-model="date"
        type="date"
        placeholder="Pick a day"
      />
      <el-pagination
        :total="100"
        :page-size="10"
      />
    </el-config-provider>
  </div>
</template>

<script setup>
import { ref, watch } from 'vue'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import en from 'element-plus/es/locale/lang/en'
import ja from 'element-plus/es/locale/lang/ja'

const locales = {
  'zh-cn': zhCn,
  'en': en,
  'ja': ja
}

const currentLang = ref('zh-cn')
const locale = ref(zhCn)
const date = ref('')

const changeLanguage = (lang) => {
  locale.value = locales[lang]
  // Also change Day.js locale
  import(`dayjs/locale/${lang}`)
}
</script>

Adding Custom Languages

If your language is not supported, you can create a custom locale file:

// custom-locale.ts
export default {
  name: 'xx',
  el: {
    colorpicker: {
      confirm: 'Confirm',
      clear: 'Clear',
    },
    datepicker: {
      now: 'Now',
      today: 'Today',
      cancel: 'Cancel',
      clear: 'Clear',
      confirm: 'OK',
      selectDate: 'Select date',
      selectTime: 'Select time',
      startDate: 'Start Date',
      startTime: 'Start Time',
      endDate: 'End Date',
      endTime: 'End Time',
      prevYear: 'Previous Year',
      nextYear: 'Next Year',
      prevMonth: 'Previous Month',
      nextMonth: 'Next Month',
      year: '',
      month1: 'January',
      month2: 'February',
      month3: 'March',
      month4: 'April',
      month5: 'May',
      : ,
      : ,
      : ,
      : ,
      : ,
      : ,
      : ,
      : ,
      : {
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
      },
      : {
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
      },
    },
    : {
      : ,
      : ,
      : ,
      : ,
    },
    
  },
}

Then use it:

import customLocale from './custom-locale'

app.use(ElementPlus, {
  locale: customLocale,
})

Best Practices

1. Persist Language Preference

Store the user's language preference in localStorage:

const savedLang = localStorage.getItem('language') || 'en'
const locale = ref(locales[savedLang])

watch(locale, (newLocale) => {
  localStorage.setItem('language', newLocale.name)
})

2. Sync with Application i18n

If using vue-i18n, sync Element Plus locale with your app locale:

import { createI18n } from 'vue-i18n'
import ElementPlus from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import en from 'element-plus/es/locale/lang/en'

const i18n = createI18n({
  locale: 'zh',
  messages: {
    zh: { /* ... */ },
    en: { /* ... */ },
  },
})

const elementLocales = {
  zh: zhCn,
  en: en,
}

app.use(i18n)
app.use(ElementPlus, {
  locale: elementLocales[i18n.global.locale],
})

3. Lazy Load Locales

For better performance, lazy load locales:

const loadLocale = async (lang) => {
  const [dayjsLocale, elementLocale] = await Promise.all([
    import(`dayjs/locale/${lang}`),
    import(`element-plus/es/locale/lang/${lang}`),
  ])
  return elementLocale.default
}

Input Parameters

When using this skill, provide:

• Target language: The language code you want to use
• Configuration method: Global or ConfigProvider
• Dynamic switching: Whether you need runtime language switching
• Date components: Whether you use DatePicker or other date components

Output Format

This skill provides:

1. Locale configuration examples
2. Language switching implementations
3. Day.js integration for date components
4. Custom locale creation guide

Usage Limitations

• Day.js locale must be imported separately for date components
• Some languages may have incomplete translations
• Custom locales need to follow the Element Plus locale structure
• CDN usage requires different import syntax