The internationalization configuration in the project mainly involves the following files and directories:

• locales/ - Stores translation files for various languages
  • en_US.json - English translation
  • zh_CN.json - Simplified Chinese translation
  • zh_TW.json - Traditional Chinese translation
• src/modules/i18n.ts - i18n initialization configuration
• src/utils/i18n.ts - i18n utility functions
• src/utils/storage.ts - Local storage utilities
• src/store/models/app.ts - Global state management
• src/components/LangSwitch.vue - Language switching component

Internationalization Implementation Principles

Initialization Configuration

In src/modules/i18n.ts, the multilingual configuration is initialized through the vue-i18n plugin

Language Switching Implementation

Language switching is mainly implemented through the following steps:

1. Provide language switching interface in the src/components/LangSwitch.vue component
2. Handle language switching logic in src/store/models/app.ts
3. Implement language setting utility functions in src/utils/i18n.ts

Local Storage

Language settings are persisted through the local storage utilities in src/utils/storage.ts

Usage

Add corresponding translation content in locales/en_US.json, locales/zh_CN.json, and locales/zh_TW.json

// en_US.json
{
  "common": {
    "newKey": "New Translation"
  }
}

// zh_CN.json
{
  "common": {
    "newKey": "新翻译"
  }
}

// zh_TW.json
{
  "common": {
    "newKey": "新翻譯"
  }
}

Using in Vue Components

In Vue components, you can use translations by obtaining the t function through useI18n()

<script setup lang="ts">
const { t } = useI18n();
</script>

<template>
  <div>{{ t("common.newKey") }}</div>
</template>

Using in TypeScript

In TypeScript files, you can use translations by obtaining the $t function through the utils tool

import { $t } from "@/utils";

console.log($t("common.newKey"));

Menu Route Translation Settings

Get corresponding translations based on the name attribute of route menus, and add corresponding translation content under route (existing) in locales/en_US.json, locales/zh_CN.json, and locales/zh_TW.json

For dynamic route translations, the data format returned by the backend is as follows:

Example of data returned by the interface with "System Management" as an example

{
  "path": "/system",
  "component": "Layout",
  "name": "/system",
  "meta": {
    "title": "系统管理",
    "icon": "material-symbols:jamboard-kiosk",
    "hidden": false,
    "alwaysShow": false,
    "params": null
  },
  "children": [
    {
      "path": "user",
      "component": "system/user/index",
      "name": "User",
      "meta": {
        "title": "用户管理",
        "icon": "ep:user-filled",
        "hidden": false,
        "keepAlive": true,
        "alwaysShow": false,
        "params": null
      }
    },
  // ......
  ]
},

⚠️ Note

When the returned data component is "Layout", follow the rules below

If component is "Layout", we will default to using path as the translation key.

• For example, if path is /system, the default translation key is System.
• If path is /system-management, the default translation key is SystemManagement.

We default to removing symbols like /, _, -, and capitalizing the first letter of each word (PascalCase).

// en_US.json
{
  "route": {
    // ......
    "System": "System",
    "SystemManagement": "System Management"
  }
}

// zh_CN.json
{
  "route": {
    // ......
    "System": "系统",
    "SystemManagement": "系统管理"
  }
}

// zh_TW.json
{
  "route": {
    // ......
    "System": "系統",
    "SystemManagement": "系統管理"
  }
}

💡 Tip

If no translation key is set, the title in meta will be used as the displayed text by default

Default Language Settings

The default language is set through the VITE_DEFAULT_LANG variable in .env.development and .env.production files

.env

# Default language enUS | zhCN | zhTW
VITE_DEFAULT_LANG='zhCN'

Notes

1. The page will reload after language switching to apply the new language settings
2. Language settings will be persistently stored locally, and the last selected language will be automatically applied on the next visit
3. When adding new translation content, corresponding translations need to be synchronized in all language files

Contributors

nuyoah

Changelog

Last edited 3 months ago

View full history

3d44aaf-refactor(en/guide): Update the path of the language switching component in the document

29aaf76-refactor(en/guide): Update the name of the language switching component in the document

127067c-docs(en/guide): Update the directory structure and multilingual documentation

16da136-docs(en/i18n): Explanation of the handling method when the translation key is missing

e1874ab-docs(en/i18n): Update the multilingual configuration documentation

b4eb45c-docs(en): Add a trailing blank line

db85ca8-docs(en): Add Internationalization (i18n) guide