1. 多语言 i18n Skill
多语言国际化 Skill，支持中英文切换、翻译管理、i18n 最佳实践
Prompt
---
name: 多语言系统
description: 多语言架构设计。⚠️ 强制：路由必须使用 ref_id 查找数据，URL 必须带语言前缀。db 使用 ref_id 方案，frontend 使用 localePath。
---
# 多语言系统
> **⚠️ 本项目采用 `ref_id` 方案实现多语言支持，开发时必须理解此架构！**
## 设计思路
本项目的多语言内容不是简单翻译，而是**各语言独立创作的内容**。
采用 `ref_id` 方案：
- 每种语言的数据是独立的一行记录
- 通过 `ref_id` 字段关联到"主版本"（中文版）
- 查询时通过 `ref_id + lang_type` 定位数据
## 表结构关系
bs_categories（大师分类）: id=1, ref_id=1, name=buffett, lang_type=zh, title=巴菲特 ← 主版本 id=7, ref_id=1, name=buffett, lang_type=en, title=Buffett ← 英文版
bs_rules（投资原则）: id=1, category_id=1, lang_type=zh, title=价格与价值 ← 中文规则 id=100, category_id=1, lang_type=en, title=Price vs Value ← 英文规则
注意：bs_rules.category_id 存的是主版本的 id（即 ref_id）
## 关键规则
| 规则 | 说明 |
| ---------------------- | ---------------------------------------------------------------- |
| `ref_id` 含义 | 中文版 `ref_id = 自己的 id`，其他语言 `ref_id = 对应中文版的 id` |
| `bs_rules.category_id` | **始终存主版本 id**，不随语言变化 |
| `bs_rules.tag_id` | **始终存主版本 id**，不随语言变化 |
## 查询逻辑
```go
// 获取分类列表
SELECT * FROM bs_categories WHERE lang_type = ? AND status = 1
// 获取规则列表（使用 ref_id）
SELECT * FROM bs_rules
WHERE category_id = ? -- 这里传的是 ref_id
AND lang_type = ?
AND status = 1前端使用
// 1. 获取分类列表（API 返回 ref_id）
const categories = await getCategoryList()
// 返回: [{ id: 7, ref_id: 1, name: "buffett", title: "Buffett" }]
// 2. 请求规则时，使用 ref_id 而非 id
const rules = await getRulesList({
category_id: category.ref_id // ✅ 用 ref_id
})支持的语言
| 代码 | 语言 | 说明 |
|---|---|---|
zh |
中文 | 主版本语言 |
en |
English | 英文 |
es |
Español | 西班牙语 |
fr |
Français | 法语 |
ar |
العربية | 阿拉伯语 |
前端 i18n URL 路由规范
⚠️ SEO 必须遵守！
路由策略
使用 @nuxtjs/i18n 模块，采用 prefix 策略：
- 每种语言都有独立的 URL 前缀
- 搜索引擎可以分别索引各语言版本
- SSR 时根据 URL 前缀确定语言
URL 格式
| 语言 | 首页 | 原则详情页 |
|---|---|---|
| 英文 | /en |
/en/principles/{slug} |
| 中文 | /zh |
/zh/principles/{slug} |
| 西班牙语 | /es |
/es/principles/{slug} |
代码规范
// ✅ 正确：使用 localePath
const localePath = useLocalePath()
router.push(localePath('/'))
<NuxtLink :to="localePath('/')">首页</NuxtLink>
// ❌ 错误：硬编码路径
router.push('/')
<NuxtLink to="/">首页</NuxtLink>语言切换
// ✅ 正确
const switchLocalePath = useSwitchLocalePath()
navigateTo(switchLocalePath('zh'))
// ❌ 错误
setLocale('zh')
window.location.reload()路径判断
// ✅ 正确：使用 includes
const isPrinciplePage = route.path.includes('/principles/')
// ❌ 错误：startsWith 不适配语言前缀
const isPrinciplePage = route.path.startsWith('/principles/')新增语言步骤
1. 修改 nuxt.config.ts
i18n: {
locales: [
// ... 现有语言
{ code: 'ja', language: 'ja-JP', file: 'ja.json', name: '日本語' },
]
}2. 创建语言文件
frontend-nuxt/i18n/locales/ja.json3. 更新语言选择器
// composables/useMaster.ts
const LANG_OPTIONS = [
// ... 现有语言
{ code: 'ja', name: '日本語', flag: '🇯🇵' },
]4. 添加数据库数据
参考上方 "表结构关系" 部分
SEO 验证清单
添加新语言后，必须验证：
- 访问
/{lang}/能正确显示对应语言首页 - 查看源代码，确认
<html lang="{lang}">正确 - 查看源代码，确认
<title>和<meta description>是对应语言 - 语言切换功能正常