Skip to content

Commit 656568a

Browse files
RSS1102RSS1102
authored
feat: 添加 i18n 本地化处理功能 (#101)
* feat: 添加 i18n 本地化处理功能 * docs: 添加 i18n 本地化处理功能文档 * chore: 移除 packageManager 锁定版本配置
1 parent 379d52a commit 656568a

5 files changed

Lines changed: 694 additions & 11 deletions

File tree

‎README-zh_CN.md‎

Lines changed: 144 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,149 @@ td-starter init tdesign-vue3-farm -type vue3 -bt farm
8888
| -bt, --buildToolType \<buildToolType>| Lite 的构建工具: vite \| webpack (默认: "vite") |
8989
| -h, --help | 显示命令的帮助 |
9090

91+
## i18n 国际化本地化
92+
93+
i18n 命令帮助你将拥有 i18n 实现的 Vue3 项目转换为本地化版本（移除 i18n 依赖）。
94+
95+
### 基础用法
96+
97+
#### 交互式操作
98+
```sh
99+
# 启动 i18n 本地化流程
100+
td-starter i18n
101+
102+
# 根据提示输入目标项目路径
103+
? 请输入目标项目路径： ./my-project
104+
```
105+
106+
#### 命令行模式
107+
```sh
108+
# 直接指定目标项目路径
109+
td-starter i18n --target ./my-project
110+
111+
# 缩写选项
112+
td-starter i18n -t ./my-project
113+
```
114+
115+
### 前置条件
116+
117+
- **项目类型**：仅支持**Vue3**项目且已配置 i18n
118+
- **项目结构**：项目必须具有以下目录结构：
119+
```
120+
src/
121+
└── locales/
122+
└── lang/
123+
├── zh_CN.json （或其他语言代码）
124+
├── en_US.json
125+
└── ...
126+
```
127+
128+
### 工作原理
129+
130+
i18n 命令执行以下操作：
131+
132+
1. **项目分析**：自动检测项目是否为已配置 i18n 的 Vue3 项目
133+
2. **语言检测**：扫描 `src/locales/lang` 目录查找所有可用的语言文件
134+
3. **语言选择**：提示选择本地化的目标语言
135+
4. **文件处理**：替换所有 i18n 函数调用为静态字符串：
136+
- `this.$t('key')` → `'translated_value'`
137+
- `$t('key')` → `'translated_value'`
138+
- `t('key')` → `'translated_value'`
139+
140+
5. **结果统计**：显示以下统计信息：
141+
- 处理的文件数量
142+
- 进行的翻译替换次数
143+
144+
### 支持的语言格式
145+
146+
以下语言代码格式会自动识别：
147+
148+
| 语言代码 | 语言名称 |
149+
|----------|--------------|
150+
| zh_CN | 简体中文 |
151+
| zh_TW | 繁體中文 |
152+
| en_US | English |
153+
| en | English |
154+
| zh | 中文 |
155+
| ja | 日本語 |
156+
| ko | 한국어 |
157+
| fr | Français |
158+
| de | Deutsch |
159+
| es | Español |
160+
| ru | Русский |
161+
162+
### 使用流程示例
163+
164+
```sh
165+
# 第一步：启动 i18n 本地化
166+
td-starter i18n
167+
168+
# 第二步：输入项目路径
169+
? 请输入目标项目路径： /Users/username/my-vue3-project
170+
171+
# 第三步：系统检测项目类型
172+
🔍 目标项目路径: /Users/username/my-vue3-project
173+
✅ 检测到项目类型: vue3
174+
175+
# 第四步：系统扫描语言配置
176+
🌍 可用语言：
177+
- 简体中文 (zh_CN)
178+
- English (en_US)
179+
180+
# 第五步：选择目标语言
181+
? 请选择要本地化的目标语言： (使用方向键选择)
182+
❯ 简体中文 (zh_CN)
183+
English (en_US)
184+
185+
# 第六步：处理完成
186+
✅ 本地化完成！
187+
处理文件: 25 个
188+
替换条目: 156 个
189+
```
190+
191+
### 重要提示
192+
193+
⚠️ **本地化后：**
194+
- i18n 配置文件和导入语句**仍然保留**
195+
- 如需完全移除 i18n 依赖，可能需要手动清理
196+
- 建议测试应用程序以确保所有翻译正确替换
197+
- 保留语言配置文件以备参考
198+
199+
### 常见问题排查
200+
201+
| 问题 | 解决方案 |
202+
|------|---------|
203+
| "无法识别项目类型" | 确保项目在正确位置有 `package.json`，且包含 Vue 3 依赖 |
204+
| "未检测到语言配置" | 验证 `src/locales/lang` 目录存在且包含 `.json` 语言文件 |
205+
| "未找到翻译: key.name" | 所选语言文件中缺少该翻译 key |
206+
| 未处理任何文件 | 检查 `src` 目录中是否存在 `.vue`、`.ts` 或 `.js` 文件 |
207+
208+
### 高级用法
209+
210+
#### 验证替换效果
211+
使用以下方式检查替换是否成功：
212+
```sh
213+
# 检查是否还存在 i18n 函数调用
214+
grep -r "\$t(" src/ --include="*.vue" --include="*.ts" --include="*.js"
215+
216+
# 检查是否还存在 i18n 导入
217+
grep -r "vue-i18n" src/ --include="*.ts" --include="*.js"
218+
```
219+
220+
#### 手动清理（可选）
221+
替换完成后，如需完全移除 i18n，可执行：
222+
```sh
223+
# 1. 移除 i18n 配置文件
224+
rm -rf src/locales/
225+
226+
# 2. 从 package.json 中移除依赖
227+
npm uninstall vue-i18n
228+
229+
# 3. 更新导入语句（手动或脚本）
230+
# 删除 import { createI18n } from 'vue-i18n'
231+
# 删除其他 i18n 相关导入
232+
```
233+
91234
## 预览
92235

93236
### Vite + React/Vue2/Vue3
@@ -108,6 +251,6 @@ td-starter init tdesign-vue3-farm -type vue3 -bt farm
108251
- [webpack-vue2](https://tencent-tdesign-starter-cli.surge.sh/template-webpack-vue2/index.html)
109252
- [webpack-vue3](https://tencent-tdesign-starter-cli.surge.sh/template-webpack-vue3/index.html)
110253

111-
## 开源协议
254+
### 开源协议
112255

113256
TDesign 遵循 [MIT 协议](https://github.com/Tencent/tdesign-starter-cli/LICENSE)。

‎README.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,149 @@ td-starter init tdesign-vue3-farm -type vue3 -bt farm
8888
| -bt, --buildToolType \<buildToolType>| The construction tool for lite: vite \| webpack (default: "vite") |
8989
| -h, --help | display help for command |
9090

91+
## i18n Localization
92+
93+
The i18n command helps you convert Vue3 projects with i18n implementations to localized versions (removing i18n dependencies).
94+
95+
### Basic Usage
96+
97+
#### Interactive Mode
98+
```sh
99+
# Start the i18n localization process
100+
td-starter i18n
101+
102+
# Then input the target project path when prompted
103+
? 请输入目标项目路径： ./my-project
104+
```
105+
106+
#### Command Mode
107+
```sh
108+
# Specify the target project path directly
109+
td-starter i18n --target ./my-project
110+
111+
# Short option
112+
td-starter i18n -t ./my-project
113+
```
114+
115+
### Requirements
116+
117+
- **Project Type**: Currently only supports **Vue3** projects with i18n setup
118+
- **Project Structure**: Your project must have the following directory structure:
119+
```
120+
src/
121+
└── locales/
122+
└── lang/
123+
├── zh_CN.json (or other language codes)
124+
├── en_US.json
125+
└── ...
126+
```
127+
128+
### How It Works
129+
130+
The i18n command performs the following operations:
131+
132+
1. **Project Analysis**: Automatically detects if the project is a Vue3 project with i18n configuration
133+
2. **Language Detection**: Scans the `src/locales/lang` directory to find all available language files
134+
3. **Language Selection**: Prompts you to choose a target language for localization
135+
4. **File Processing**: Replaces all i18n function calls with static strings:
136+
- `this.$t('key')` → `'translated_value'`
137+
- `$t('key')` → `'translated_value'`
138+
- `t('key')` → `'translated_value'`
139+
140+
5. **Result Summary**: Shows statistics including:
141+
- Number of files processed
142+
- Number of translation replacements made
143+
144+
### Supported Language Formats
145+
146+
The following language code formats are automatically recognized:
147+
148+
| Language Code | Language Name |
149+
|---------------|-------------------|
150+
| zh_CN | 简体中文 |
151+
| zh_TW | 繁體中文 |
152+
| en_US | English |
153+
| en | English |
154+
| zh | 中文 |
155+
| ja | 日本語 |
156+
| ko | 한국어 |
157+
| fr | Français |
158+
| de | Deutsch |
159+
| es | Español |
160+
| ru | Русский |
161+
162+
### Example Workflow
163+
164+
```sh
165+
# Step 1: Navigate to where tdesign-starter-cli is installed
166+
td-starter i18n
167+
168+
# Step 2: Input project path
169+
? 请输入目标项目路径： /Users/username/my-vue3-project
170+
171+
# Step 3: System detects project type
172+
🔍 目标项目路径: /Users/username/my-vue3-project
173+
✅ 检测到项目类型: vue3
174+
175+
# Step 4: System scans language configurations
176+
🌍 可用语言：
177+
- 简体中文 (zh_CN)
178+
- English (en_US)
179+
180+
# Step 5: Select target language
181+
? 请选择要本地化的目标语言： (Use arrow keys to select)
182+
❯ 简体中文 (zh_CN)
183+
English (en_US)
184+
185+
# Step 6: Process completed
186+
✅ 本地化完成！
187+
处理文件: 25 个
188+
替换条目: 156 个
189+
```
190+
191+
### Important Notes
192+
193+
⚠️ **After localization:**
194+
- The i18n configuration files and import statements are **still preserved**
195+
- Manual cleanup may be required if you want to completely remove i18n dependencies
196+
- Test your application to ensure all translations are correctly replaced
197+
- Keep your language configuration files for reference
198+
199+
### Troubleshooting
200+
201+
| Issue | Solution |
202+
|-------|----------|
203+
| "无法识别项目类型" | Ensure your project has `package.json` with Vue 3 dependencies in the correct location |
204+
| "未检测到语言配置" | Verify the `src/locales/lang` directory exists and contains `.json` language files |
205+
| "未找到翻译: key.name" | The translation key is missing in the selected language file |
206+
| No files processed | Check if there are `.vue`, `.ts`, or `.js` files in the `src` directory |
207+
208+
### Advanced Usage
209+
210+
#### Verify Replacement Results
211+
Use the following methods to check if the replacement was successful:
212+
```sh
213+
# Check if there are still i18n function calls
214+
grep -r "\$t(" src/ --include="*.vue" --include="*.ts" --include="*.js"
215+
216+
# Check if there are still i18n imports
217+
grep -r "vue-i18n" src/ --include="*.ts" --include="*.js"
218+
```
219+
220+
#### Manual Cleanup (Optional)
221+
After replacement, to completely remove i18n, you can execute:
222+
```sh
223+
# 1. Remove i18n configuration files
224+
rm -rf src/locales/
225+
226+
# 2. Remove dependencies from package.json
227+
npm uninstall vue-i18n
228+
229+
# 3. Update import statements (manually or via script)
230+
# Delete import { createI18n } from 'vue-i18n'
231+
# Delete other i18n related imports
232+
```
233+
91234
## Preview
92235

93236
### Vite + React/Vue2/Vue3

0 commit comments

Comments
 (0)