文档 / 多语言

多语言

APP 面向欧美、日韩等市场：REST 的 message、分类展示名 name、验证码邮件会随语言变化。本门户与管理端仍为中文。业务逻辑请以 code、slug 为准，不要用 message 原文做 if 判断。

默认语言

未传语言参数时使用 en。

支持的语言

code	语言	主要市场
en	English	美国 / 国际默认
zh	简体中文	中国大陆等；zh-CN / zh-Hans 归一为 zh
ja	日本語	日本
ko	한국어	韩国
de	Deutsch	德国等
fr	Français	法国等
es	Español	西班牙等
it	Italiano	意大利
pt	Português	葡萄牙等
nl	Nederlands	荷兰等
pl	Polski	波兰

区域码会归一到主语言：en-US → en，zh-CN / zh-Hans → zh，ja-JP → ja，ko-KR → ko，fr-FR → fr 等。别名：cn → zh，jp → ja，kr → ko。繁体（zh-TW 等）暂回落简体。

语言识别优先级（高 → 低）

1. Query：?lang=ja 或 ?locale=ja（优先级最高）
2. Body / form：JSON 或表单字段 lang、locale（Http::params 合并后生效）
3. 请求头：X-Lang 或 X-Locale
4. 请求头：Accept-Language（如 ja-JP,ja;q=0.9,en;q=0.8）
5. 回落：配置默认 en

会随语言变化的字段

项	说明
code	不变。客户端分支处理请用数字错误码。
message	随语言变化；可直接 toast。同一 code 不同语言文案不同。
Content-Language	响应头带回实际生效语言，如 en / ja。
分类 name	/pattern-categories 与图纸 category.name 按 slug 本地化；slug 固定（fruit、game…）。
已注销用户昵称	作者已注销时 nickname 为本地化「Deleted user」等；库内管理端仍可能显示中文。
验证码邮件	主题与正文按请求语言发送（mailgun）；mock 模式仅写日志。
debug_hint	send-code 在 debug+mock 时的提示文案也会本地化。

不随语言变化

• 图纸 title / description（UGC，保持作者原文）
• 用户自填 nickname、signature、bio
• 管理后台、本开发者门户与 API 文档正文（固定中文）
• 错误码 code 数值与路径 slug

分类 name 对照（节选）

筛选 / 业务用 slug；界面展示用 name（随 lang 变化）。

slug	en	zh 简体	ja	ko
ip	IP	IP	IP	IP
character	Character	人物	キャラクター	캐릭터
scenery	Scenery	风景	風景	풍경
game	Game	游戏	ゲーム	게임
fruit	Fruit	水果	フルーツ	과일
food	Food	食品	フード	음식
animal	Animal	动物	動物	동물
other	Other	其他	その他	기타

请求示例

Query 指定日语

GET /api/pattern-categories?lang=ja
Accept: application/json

categories[].name 为日文（如 キャラクター、フルーツ）；slug 仍为 character、fruit。

Accept-Language

GET /api/auth/login
Accept-Language: ko-KR,ko;q=0.9,en;q=0.8
Content-Type: application/json

{"email":"","password":""}

缺参时 message 为韩文，例如「이메일과 비밀번호를 입력하세요」。

Body 指定语言

POST /api/auth/login
Content-Type: application/json

{"email":"[email protected]","password":"x","lang":"de"}

message 为德文（如登录失败时的提示）。

客户端建议

• 启动时把系统语言映射到 supported 列表，请求统一带 lang 或 Accept-Language。
• UI 文案（Tab、按钮）放在 APP 本地化资源；后端只保证 message / 字典类字段。
• 判断失败原因用 code（如 40101 跳转登录），不要 parse message 字符串。
• 筛选分类用 category=fruit 等 slug，不要用 name。
• 模拟请求调试可加 ?lang=ja 或在 Body 写 "lang":"ja"。