# Multi-Language Internationalization (i18n) Design Specification

> **Date:** 2026-06-24
> **Status:** Approved
> **Scope:** Backend (Spring), Frontend (Vue 3), Miniapp, Database Dictionaries

---

## [S1] Backend i18n

### Current State
- Spring MessageSource configured at I18nConfig with SessionLocaleResolver
- Param name: lang
- Existing: messages.properties (fallback), messages_zh_CN.properties (56 keys)
- Miniapp: messages.properties (46 keys)

### Design
- Create messages_en_US.properties and messages_vi_VN.properties in both main app and miniapp
- Translate all 56+ keys per language
- No code changes needed Spring already supports this via MessageUtils.message(key, args)

---

## [S2] Database Dictionary Multi-Language

### Current State
- sys_dict_data table with fields: dictCode, dictSort, dictLabel, dictValue, dictType, cssClass, listClass, isDefault, status, pyStr
- 124+ Java files reference SysDictData and DictUtils

### Design
- Flyway migration: ADD COLUMN dict_value_en VARCHAR(200), dict_value_vi VARCHAR(200)
- Entity: Add dictValueEn, dictValueVi fields to SysDictData.java
- Service: Update DictUtils.getDictLabel() to return locale-aware label
- Query fallback: if target language field is null use dictLabel (Chinese)
- Management UI: Add en/vi input fields to dict data edit dialog

---

## [S3] Frontend i18n

### Current State
- 724 Vue files with hardcoded Chinese text
- Element Plus hardcoded to zhCn in main.js:120
- No vue-i18n dependency
- No i18n directory structure

### Design
- Install vue-i18n@latest (v11, Composition API mode)
- Directory: src/i18n/ with index.js + locales/{zhCN,enUS,viVN}.json
- Language switching: Cookie + localStorage + user preference
- Component: LanguageSwitcher dropdown in navbar
- Element Plus: Dynamic locale switching via ElLocale.use()
- VXE Table: Dynamic locale via VxeUI.setLang()
- Extraction: Node.js script to scan all .vue/.js for Chinese text
- Migration: Module-by-module replacement of hardcoded Chinese with $t(key)

### JSON Structure
nav.*        Navigation menu labels
common.*     Buttons, labels, messages (shared)
login.*      Login page
dict.*       Dictionary values (gender, status, etc.)
module.*     Business module specific (registration, pharmacy, etc.)

---

## [S4] Dictionary Management UI

- Add multilanguage tab to src/views/system/dict/data.vue
- Input fields for dict_value_en and dict_value_vi
- Save to backend via existing dict update API extended with new fields

---

## [S5] Testing

### Backend
- mvn clean compile -DskipTests BUILD SUCCESS
- mvn test all tests pass
- API test: curl -H Accept-Language: en returns English messages

### Frontend
- npm run build:dev BUILD SUCCESS
- npm run lint no errors
- Manual: Switch language all UI text changes refresh persists

---

## Execution Preference

execution-style: subagent Each task executed by a fresh subagent.