国际化
维护中英文消息、产品覆盖文案、Paraglide 生成结果与成对 MDX 内容。
消息、产品文案与文章分开维护
| 位置 | 用途 |
|---|---|
packages/i18n/messages/en.json、zh.json | 模板基础消息 |
packages/i18n/messages/en.mvp.json、zh.mvp.json | 你的产品覆盖文案 |
apps/web/src/lib/locale.tsx | 页面语言、翻译函数与链接前缀 |
apps/web/src/content/*.en.mdx、*.zh.mdx | 公开页长内容 |
apps/web/src/paraglide | Vite 生成的消息模块，不手工编辑 |
产品覆盖保留上游消息结构，适合修改品牌、按钮和产品介绍。新增基础 key 时保持 en/zh 配对，再在组件里使用已有的 useLocale 与 t，而不是在页面散落字符串。
维护一个消息
- 在 en.json 和 zh.json 增加同名 key，值使用对应语言。
- 如果只是改现有产品文案，优先写入 en.mvp.json / zh.mvp.json。
- 在组件中调用
const { t, href } = useLocale()，并使用t('existing_key')。 - 运行开发或构建，使 Paraglide 更新生成代码；类型错误提示缺少 key 时回到消息文件修复。
示意组件：
const { t, href } = useLocale();
return <a href={href('/app/files')}>{t('files')}</a>;上例的 key 必须存在于当前消息表；添加自己的 key 时同步声明，不以类型断言隐藏遗漏。
路由与切换
默认英文路径为 /pricing、/app、/auth/login，中文为 /zh/pricing、/zh/app、/zh/auth/login。页面 hook 根据当前路径确定界面语言，href 包装器负责前缀。Paraglide 配置还包含 URL、cookie 与默认语言策略；不要假设只改 cookie 就会改变当前页面 URL。
使用现有切换入口保留当前页面位置。API 永远使用 /api/*，不能把语言前缀用于健康、登录回调、上传或 Webhook。
维护 MDX
公开文章按 <slug>.en.mdx 与 <slug>.zh.mdx 成对放在 content 根目录。当前加载器使用静态 glob，不是官网的 Fumadocs 目录树，也不自动递归读取任意子目录。
例如法律页请求的 legal 前缀会在内容加载时处理；请先检查 modules/public 的 slug 映射再命名。缺少文章时返回空内容，不会自动生成翻译，所以新增页面应同时补齐两种语言并检查最终页面。
增加第三种语言
这是需要代码适配的工作：增加消息、产品覆盖和文章，更新 Paraglide/inlang 配置、locale 类型、路径解析、链接切换、SEO hreflang 和测试。不能仅复制一个 ja.json 就承诺全站支持日语。
官网目前八语入口与 Flare 模板自身中英文能力不同，官网其他语言的文档回退也不代表模板自动支持这些语言。
验证与排障
- 检查公开页、验证码/密码登录、工作台和后台两种语言。
- 中文切换后仍保留当前模块，刷新 URL 不丢语言。
- 新消息显示 key：检查生成是否成功、基础消息与覆盖是否同名。
- 中文页面文章为空：检查文件名、slug 与 glob 目录，而不是只改消息 JSON。
- 运行
pnpm build、pnpm type-check，并执行桌面及移动端语言切换测试。