frontend-internationalization-best-practices

国际化最佳实践

使用 remix-i18next 构建 React Router 国际化配置的指南。重点关注中间件检测、区域设置存储、类型安全以及客户端与服务器同步。

适用场景

• 为 React Router 应用添加国际化
• 配置 remix-i18next 中间件
• 实现语言切换或区域设置检测
• 从 /api/locales 提供区域设置资源

规则摘要

配置与中间件（关键）

setup-middleware - @rules/setup-middleware.md

配置 createI18nextMiddleware 和类型安全的资源。

export const [i18nextMiddleware, getLocale, getInstance] =
  createI18nextMiddleware({
    detection: {
      supportedLanguages: ["es", "en"],
      fallbackLanguage: "en",
      cookie: localeCookie,
    },
    i18next: { resources },
    plugins: [initReactI18next],
  });

locales-structure - @rules/locales-structure.md

为每种语言定义区域设置资源并重新导出。

// app/locales/en/translation.ts
export default { title: "Example" };

命名空间（高优先级）

namespaces-strategy - @rules/namespaces-strategy.md

小型应用使用单个命名空间；大型应用使用多个命名空间。

// Large app: common + route namespaces
export default { common, home, notFound };

区域设置检测与持久化（关键）

locale-detection - @rules/locale-detection.md

优先使用 Cookie/会话以提高速度，并以数据库作为事实来源。

export const [i18nextMiddleware, getLocale] = createI18nextMiddleware({
  detection: { cookie: localeCookie, fallbackLanguage: "en" },
});

language-switcher - @rules/language-switcher.md

将区域设置存储在 Cookie/会话中，并保持同步。

return data(
  { locale },
  { headers: { "Set-Cookie": await localeCookie.serialize(locale) } },
);

客户端与服务器集成（关键）

root-locale-sync - @rules/root-locale-sync.md

将区域设置发送到 UI，并同步 <html lang dir>。

export async function loader({ context }: Route.LoaderArgs) {
  let locale = getLocale(context);
  return data(
    { locale },
    { headers: { "Set-Cookie": await localeCookie.serialize(locale) } },
  );
}

entry-client-init - @rules/entry-client-init.md

使用 htmlTag 检测初始化 i18next 客户端。

i18next.init({ detection: { order: ["htmlTag"], caches: [] } });

entry-server-provider - @rules/entry-server-provider.md

在 SSR 中通过 I18nextProvider 重用中间件实例。

<I18nextProvider i18n={getInstance(routerContext)}>
  <ServerRouter context={entryContext} url={request.url} />
</I18nextProvider>

资源路由与缓存（高优先级）

locales-resource-route - @rules/locales-resource-route.md

通过验证和缓存头提供 /api/locales/:lng/:ns。

return data(namespaces[ns.data], { headers });

UI 用法（中优先级）

use-bound-t-in-loader - @rules/use-bound-t-in-loader.md

在加载器中使用绑定的 t()，并在组件中使用 useTranslation。

let t = getInstance(context).getFixedT(locale);

未找到页面（中优先级）

not-found-i18n - @rules/not-found-i18n.md

提供 404 路由，以便中间件运行并加载翻译。