多语言

多语言

提供的能力

@nocobase/app-plugin-i18n 提供应用运行时语言切换接口与 hooks。翻译资源、命名空间和翻译机制由框架负责；本插件负责让用户选择语言并同步服务端偏好。

插件提供切换与同步行为；翻译资源和选择器外观仍由应用负责。

接口为 GET /api/i18n/locales 和 PUT /api/i18n/locale。若服务端不支持所选语言，会保存 en-US 并返回 fallback: true，浏览器界面仍保留自己的语言；网络失败也不会自动撤销浏览器选择。

开发提示词（交给当前应用目录中的 Coding Agent）：

请使用多语言插件，为应用接入中英文切换。
检查并补齐客户端和服务端资源加载器，复用 useAppLocale 与模板已有选择器。
切换时处理 loading 和失败，保留浏览器选择，并在启动时同步服务端语言。
验证刷新、服务端不支持的语言、网络失败和多标签页行为，不实现业务内容自动翻译。

完成标志：切换后应用与插件文案更新，刷新保留选择，服务端回退或网络失败有明确处理。

以下是实现本例时的接入位置与预期界面变化；它们是开发说明，具体文件名沿用当前应用结构。

接入位置	代码或配置变化	界面与行为变化
client/locales、server/locales	补充资源及加载器	可选择语言来自应用实际资源
顶栏语言选择器	使用 useAppLocale，处理 switching 与失败	页面和插件文案随选择更新
布局启动同步与错误展示	使用 useSyncServerLocale，按稳定原因展示错误	服务端偏好得到同步，回退行为可解释

新增一种语言时，为应用补充相应资源与加载器。其他插件即使提供某种语言，也不会自动将其加入应用的语言选择列表。默认语言配置为：

i18n:
  defaultLocale: zh-CN

APP_DEFAULT_LOCALE 可以覆盖默认值。应用未提供资源的默认语言不会作为一个新选项出现。

插件提供行为，选择器外观由应用负责。在 AppClientRoot 内使用：

import { useAppLocale } from '@nocobase/app-plugin-i18n/client';

const { locale, locales, setLocale, switching } = useAppLocale();

这是组件内的调用片段。用 locales 渲染选项，选择后调用 setLocale(next)，切换期间按 switching 禁用重复操作，并处理 Promise 失败。

切换会加载各命名空间资源、更新界面与 HTML 语言方向、保存浏览器偏好并通知服务端。各插件共享翻译运行时，无需另写一套跟随切换逻辑。

多个标签页共享会话的服务端语言，可能出现一个标签页切换后另一个标签页的接口提示也改变。自定义界面可按稳定的 error.reason 显示对应语言文案。

本插件不提供业务内容的自动翻译或翻译管理后台。资源编写见客户端多语言和服务端多语言。

上述检查是接入后的验收要求，不表示本文已完成运行验证。让 Agent 报告实际改动、执行过的检查和未验证项；项目指引、Skills 与通用检查流程见持续开发应用和测试。