Complete Guide to MineAdmin Internationalization Configuration

MineAdmin's frontend is built on Vue i18n v11, providing a comprehensive internationalization solution that supports multi-language switching, dynamic language pack loading, and modular translation management. This document details the system's internationalization implementation mechanisms and usage methods.

Overview

Supported Languages

Simplified Chinese (zh_CN) - Default language
Traditional Chinese (zh_TW)
English (en)

Core Features

🌐 Dynamic multi-language switching
📦 Modular language pack management
⚡ Dynamic language pack loading
🔧 Development tool integration
📱 Global and local scope support
🎯 TypeScript type safety

Technology Stack

Vue i18n: 11.1.2
Build Plugin: @intlify/unplugin-vue-i18n 6.0.3
Language Format: YAML (supports JSON)
Type System: TypeScript

Project Configuration

System Initialization

The system initializes internationalization configuration in /web/src/bootstrap.ts:

typescript

// Source location: web/src/bootstrap.ts:44-67
// GitHub: https://github.com/mineadmin/mineadmin/blob/master/web/src/bootstrap.ts

async function createI18nService(app: App) {
  // Automatically scan language pack files
  const locales: any[] = Object.entries(import.meta.glob('./locales/*.y(a)?ml')).map(([key]: any) => {
    const [, value, label] = key.match(/^.\/locales\/(\w+)\[([^[\]]+)\]\.yaml$/)
    return { label, value }
  })
  
  useUserStore().setLocales(locales)
  
  // Process message format
  Object.keys(messages as any).map((name: string) => {
    const matchValue = name.match(/(\w+)/) as RegExpMatchArray | null
    if (messages && matchValue) {
      messages[matchValue[1]] = messages[name]
      delete messages[name]
    }
  })

  // Create i18n instance
  app.use(createI18n({
    legacy: false,                    // Use Composition API
    globalInjection: true,            // Global injection
    fallbackLocale: 'zh_CN',         // Fallback language
    locale: useUserStore().getLanguage(), // Current language
    silentTranslationWarn: true,      // Silent translation warnings
    silentFallbackWarn: true,         // Silent fallback warnings
    messages,                         // Language pack data
  }))
}

System Architecture

Architecture Diagram

mermaid

graph TB
    A[Vue App] --> B[Bootstrap]
    B --> C[I18n Service]
    C --> D[createI18n]
    D --> E[Global Messages]
    D --> F[Local Messages]
    
    E --> G[Core Locales]
    E --> H[Module Locales]
    E --> I[Plugin Locales]
    
    F --> J[Component i18n blocks]
    
    K[useTrans Hook] --> L[Global Translation]
    K --> M[Local Translation]
    
    N[useLocalTrans Hook] --> M
    
    G --> O[/src/locales/*.yaml]
    H --> P[/src/modules/*/locales/*.yaml]
    I --> Q[/src/plugins/*/locales/*.yaml]
    
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style K fill:#fff3e0
    style N fill:#fff3e0

File Structure

web/src/
├── locales/                           # Core language packs
│   ├── zh_CN[简体中文].yaml
│   ├── en[English].yaml
│   └── zh_TW[繁體中文].yaml
├── modules/                           # Module language packs
│   └── base/
│       └── locales/
│           ├── zh_CN[简体中文].yaml
│           ├── en[English].yaml
│           └── zh_TW[繁體中文].yaml
├── plugins/                           # Plugin language packs
│   └── mine-admin/
│       └── code-generator/
│           └── web/
│               └── locales/
│                   ├── zh_CN[简体中文].yaml
│                   ├── en[English].yaml
│                   └── zh_TW[繁體中文].yaml
└── hooks/                             # Internationalization Hooks
    ├── auto-imports/
    │   └── useTrans.ts               # Auto-imported translation Hook
    └── useLocalTrans.ts              # Local translation Hook

Language Pack Management

File Naming Convention

Language pack files must follow the specific format: language identifier[language name].yaml

bash

# Correct naming format
zh_CN[简体中文].yaml
en[English].yaml  
zh_TW[繁體中文].yaml

# Incorrect naming format
zh_CN.yaml         # Missing language name
en[英文].yaml      # Incorrect language name
zh-CN[简体中文].yaml  # Incorrect language identifier format

Global Language Packs

The system automatically scans language packs from three locations:

Core language packs: src/locales/
Module language packs: src/modules/<module name>/locales/
Plugin language packs: src/plugins/<plugin name>/locales/

Important Note

Module and plugin language pack filenames must exactly match those in src/locales, otherwise console warnings about missing translation keys will appear.

Language Pack Content Example

Core language pack example (src/locales/zh_CN[简体中文].yaml):

yaml

# Login form
loginForm:
  loginButton: 登录
  passwordPlaceholder: 请输入密码
  codeLabel: 验证码
  usernameLabel: 账户

# CRUD operations
crud:
  cancel: 取消
  save: 保存
  ok: 确定
  add: 新增
  edit: 编辑
  delete: 删除
  createSuccess: 创建成功
  updateSuccess: 修改成功
  delMessage: 是否删除所选中数据？

# Form validation
form:
  pleaseInput: 请输入{msg}
  pleaseSelect: 请选择{msg}
  requiredInput: '{msg}必填'

Local Language Packs

Define local language packs in Vue components:

vue

<template>
  <div>
    <h1>{{ t('welcome') }}</h1>
    <p>{{ t('description') }}</p>
  </div>
</template>

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

<i18n lang="yaml">
zh_CN:
  welcome: 欢迎使用
  description: 这是一个示例页面
zh_TW:
  welcome: 歡迎使用
  description: 這是一個示例頁面
en:
  welcome: Welcome
  description: This is a sample page
</i18n>

Hook System Details

useTrans Hook

Source location: web/src/hooks/auto-imports/useTrans.ts
GitHub: https://github.com/mineadmin/mineadmin/blob/master/web/src/hooks/auto-imports/useTrans.ts

typescript

import { useI18n } from 'vue-i18n'
import type { ComposerTranslation } from 'vue-i18n'

export interface TransType {
  globalTrans: ComposerTranslation
  localTrans: ComposerTranslation
}

export function useTrans(key: any | null = null): TransType | string | any {
  const global = useI18n()
  const local = useI18n({
    inheritLocale: true,
    useScope: 'local',
  })

  if (key === null) {
    return {
      localTrans: local.t,
      globalTrans: global.t,
    }
  }
  else {
    // First look for global translation, then fall back to local
    return global.te(key) ? global.t(key) : local.te(key) ? local.t(key) : key
  }
}

useLocalTrans Hook

Source location: web/src/hooks/useLocalTrans.ts
GitHub: https://github.com/mineadmin/mineadmin/blob/master/web/src/hooks/useLocalTrans.ts

typescript

import { useI18n } from 'vue-i18n'
import type { ComposerTranslation } from 'vue-i18n'

export function useLocalTrans(key: any | null = null): string | ComposerTranslation | any {
  const { t } = useI18n({
    inheritLocale: true,
    useScope: 'local',
  })
  return key === null ? t as ComposerTranslation : t(key) as string
}

Usage Methods

Basic Usage

1. Global and Local Translation Objects

vue

<script setup lang="ts">
import type { TransType } from '@/hooks/auto-imports/useTrans.ts'

// Get translation objects
const i18n = useTrans() as TransType
const t = i18n.globalTrans  // Global translation function
const localT = i18n.localTrans  // Local translation function

// Usage examples
const title = t('crud.createSuccess')  // "创建成功"
const localTitle = localT('welcome')   // Translation defined in component
</script>

2. Direct Translation Calls

typescript

// Smart translation: prioritizes global, falls back to local
const message = useTrans('crud.updateSuccess')  // "修改成功"

// Local-only translation
const localMessage = useLocalTrans('description')

Real-World Project Example

Source location: web/src/modules/base/views/permission/user/index.vue
GitHub: https://github.com/mineadmin/mineadmin/blob/master/web/src/modules/base/views/permission/user/index.vue

vue

<script setup lang="tsx">
import type { TransType } from '@/hooks/auto-imports/useTrans.ts'

// Get internationalization object
const i18n = useTrans() as TransType
const t = i18n.globalTrans

// Using translations in dialog configuration
const maDialog: UseDialogExpose = useDialog({
  ok: ({ formType }, okLoadingState: (state: boolean) => void) => {
    // Show different messages based on operation type
    switch (formType) {
      case 'add':
        formRef.value.add().then((res: any) => {
          res.code === ResultCode.SUCCESS 
            ? msg.success(t('crud.createSuccess'))  // "创建成功"
            : msg.error(res.message)
        })
        break
      case 'edit':
        formRef.value.edit().then((res: any) => {
          res.code === 200 
            ? msg.success(t('crud.updateSuccess'))  // "修改成功"
            : msg.error(res.message)
        })
        break
    }
  },
})

// Using translations in table configuration
const options = ref<MaProTableOptions>({
  header: {
    mainTitle: () => t('baseUserManage.mainTitle'),
    subTitle: () => t('baseUserManage.subTitle'),
  },
})
</script>

Parameterized Translations

vue

<template>
  <div>
    <!-- Displays: 请输入用户名 -->
    <el-input :placeholder="t('form.pleaseInput', { msg: '用户名' })" />
    
    <!-- Displays: 用户名必填 -->
    <span class="error">{{ t('form.requiredInput', { msg: '用户名' }) }}</span>
  </div>
</template>

<script setup lang="ts">
const { globalTrans: t } = useTrans()
</script>

Direct Usage in Templates

vue

<template>
  <div>
    <!-- Using global $t function -->
    <el-button>{{ $t('crud.save') }}</el-button>
    
    <!-- Using Hook -->
    <el-button>{{ t('crud.cancel') }}</el-button>
  </div>
</template>

Advanced Features

Dynamic Language Switching

typescript

// Switch to English
const { locale } = useI18n()
locale.value = 'en'

// Or use user store
const userStore = useUserStore()
userStore.setLanguage('en')

Checking Translation Key Existence

typescript

const { te, t } = useI18n()

// Check if key exists
if (te('some.key')) {
  const translation = t('some.key')
} else {
  console.warn('Translation key not found: some.key')
}

Pluralization Handling

yaml

# Language pack definition
en:
  cart:
    items: 'no items | one item | {count} items'
zh_CN:
  cart:
    items: '{count} 个商品'

typescript

// Usage
const itemCount = ref(5)
const message = t('cart.items', itemCount.value)  // "5 个商品"

Performance Optimization

Lazy Loading Language Packs

typescript

// On-demand language pack loading
const loadLanguage = async (locale: string) => {
  try {
    const messages = await import(`../locales/${locale}[${getLocaleName(locale)}].yaml`)
    const { global } = useI18n()
    global.setLocaleMessage(locale, messages.default)
    global.locale.value = locale
  } catch (error) {
    console.error(`Failed to load language pack: ${locale}`, error)
  }
}

Caching Optimization

typescript

// Cache translation results
const translationCache = new Map<string, string>()

const cachedT = (key: string, ...args: any[]) => {
  const cacheKey = `${key}-${JSON.stringify(args)}`
  if (translationCache.has(cacheKey)) {
    return translationCache.get(cacheKey)
  }
  
  const result = t(key, ...args)
  translationCache.set(cacheKey, result)
  return result
}

Debugging and Troubleshooting

Common Issues

1. Missing Translation Keys

Issue: Console warning Not found 'xxx' key in 'zh_CN' locale messages.

Solution:

typescript

// Check if key exists
const { te, t } = useI18n()
const safeT = (key: string, fallback: string = key) => {
  return te(key) ? t(key) : fallback
}

2. Module Language Packs Not Working

Issue: Module or plugin language packs not being loaded

Solution:

Ensure filename format is correct: zh_CN[简体中文].yaml
Check if file path is within scan scope
Verify YAML syntax is correct

3. Type Errors

Issue: TypeScript type checking fails

Solution:

typescript

// Use correct type definitions
import type { TransType } from '@/hooks/auto-imports/useTrans.ts'

const i18n = useTrans() as TransType
const t = i18n.globalTrans  // Type-safe translation function

Development Tools

Recommended IDE Plugins

VSCode: i18n Ally
WebStorm: Easy i18n

Debugging Tips

typescript

// Enable verbose logging
const i18n = createI18n({
  // ... other configurations
  silentTranslationWarn: false,  // Show translation warnings
  silentFallbackWarn: false,     // Show fallback warnings
  missingWarn: true,             // Show missing warnings
  fallbackWarn: true,            // Show fallback warnings
})

Testing Strategy

Unit Testing

typescript

// tests/i18n.spec.ts
import { mount } from '@vue/test-utils'
import { createI18n } from 'vue-i18n'

describe('i18n Component', () => {
  const i18n = createI18n({
    legacy: false,
    locale: 'zh_CN',
    messages: {
      zh_CN: { hello: '你好' },
      en: { hello: 'Hello' }
    }
  })

  it('renders correct translation', () => {
    const wrapper = mount(TestComponent, {
      global: { plugins: [i18n] }
    })
    expect(wrapper.text()).toContain('你好')
  })

  it('switches language correctly', async () => {
    i18n.global.locale.value = 'en'
    await wrapper.vm.$nextTick()
    expect(wrapper.text()).toContain('Hello')
  })
})

E2E Testing

typescript

// tests/e2e/i18n.spec.ts
test('language switching works', async ({ page }) => {
  await page.goto('/login')
  
  // Check default language
  await expect(page.locator('.login-title')).toHaveText('登录')
  
  // Switch language
  await page.click('.language-switcher')
  await page.click('[data-lang="en"]')
  
  // Check language switch effect
  await expect(page.locator('.login-title')).toHaveText('Login')
})

Extension Development

Adding New Languages

Create language pack file:

bash

# Create new language file in src/locales/
touch src/locales/ja[日本語].yaml

Add translation content:

yaml

# ja[日本語].yaml
loginForm:
  loginButton: ログイン
  passwordPlaceholder: パスワードを入力してください
  
crud:
  save: 保存
  cancel: キャンセル

Update language configuration:

typescript

// If needed, add new language support during initialization
const supportedLocales = ['zh_CN', 'en', 'zh_TW', 'ja']

Custom Translation Logic

typescript

// Create custom translation Hook
export function useCustomTrans() {
  const { t, te } = useI18n()
  
  return {
    t: (key: string, fallback?: string) => {
      if (te(key)) {
        return t(key)

Complete Guide to MineAdmin Internationalization Configuration ​

Overview ​

Supported Languages ​

Core Features ​

Technology Stack ​

Project Configuration ​

System Initialization ​

System Architecture ​

Architecture Diagram ​

File Structure ​

Language Pack Management ​

File Naming Convention ​

Global Language Packs ​

Language Pack Content Example ​

Local Language Packs ​

Hook System Details ​

useTrans Hook ​

useLocalTrans Hook ​

Usage Methods ​

Basic Usage ​

1. Global and Local Translation Objects ​

2. Direct Translation Calls ​

Real-World Project Example ​

Parameterized Translations ​

Direct Usage in Templates ​

Advanced Features ​

Dynamic Language Switching ​

Checking Translation Key Existence ​

Pluralization Handling ​

Performance Optimization ​

Lazy Loading Language Packs ​

Caching Optimization ​

Debugging and Troubleshooting ​

Common Issues ​

1. Missing Translation Keys ​

2. Module Language Packs Not Working ​

3. Type Errors ​

Development Tools ​

Recommended IDE Plugins ​

Debugging Tips ​

Testing Strategy ​

Unit Testing ​

E2E Testing ​

Extension Development ​

Adding New Languages ​

Custom Translation Logic ​

Complete Guide to MineAdmin Internationalization Configuration

Overview

Supported Languages

Core Features

Technology Stack

Project Configuration

System Initialization

System Architecture

Architecture Diagram

File Structure

Language Pack Management

File Naming Convention

Global Language Packs

Language Pack Content Example

Local Language Packs

Hook System Details

useTrans Hook

useLocalTrans Hook

Usage Methods

Basic Usage

1. Global and Local Translation Objects

2. Direct Translation Calls

Real-World Project Example

Parameterized Translations

Direct Usage in Templates

Advanced Features

Dynamic Language Switching

Checking Translation Key Existence

Pluralization Handling

Performance Optimization

Lazy Loading Language Packs

Caching Optimization

Debugging and Troubleshooting

Common Issues

1. Missing Translation Keys

2. Module Language Packs Not Working

3. Type Errors

Development Tools

Recommended IDE Plugins

Debugging Tips

Testing Strategy

Unit Testing

E2E Testing

Extension Development

Adding New Languages

Custom Translation Logic