frontend-internationalization-best-practices

国際化のベストプラクティス

remix-i18next を使用して React Router の i18n を構成するためのガイドラインです。ミドルウェアによる検出、ロケールの保存、型安全性、クライアントとサーバーの同期に重点を置いています。

適用する場面

• React Router アプリに i18n を追加するとき
• 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／セッションを使用し、DB を信頼できる情報源とします。

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（中）

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

ミドルウェアが実行され、翻訳が読み込まれるように、404 ルートを用意します。