多言語化

多言語化

機能

@nocobase/app-plugin-i18n は、実行時の言語の切り替えと、サーバーの設定の同期を提供します。翻訳のリソース、名前空間、翻訳そのものはフレームワークが担います。

プラグインは切り替えと同期を提供し、リソースと言語の選択の表示はアプリが担います。

シナリオと例

例：英語と中国語

両方のランタイムに en-US と zh-CN のリソースを用意します。
言語の選択を組み込むか、テンプレートの実装を再利用します。
切り替えて、ページ、プラグインの内容、サーバーのエラーを確認します。
再読み込みして保存されることを確認し、起動時の調整には useSyncServerLocale() を使います。

エンドポイントは GET /api/i18n/locales と PUT /api/i18n/locale です。サポートされていないサーバーの言語は fallback: true とともに en-US にフォールバックし、ブラウザーは選択を保ちます。通信の失敗でも、ブラウザーの選択は元に戻りません。

開発用のプロンプト（アプリのディレクトリで作業するコーディングエージェント向け）：

Localization を使って、英語と中国語の切り替えを追加してください。クライアントとサーバーの
リソースのローダーを確認し、useAppLocale と既存のテンプレートの操作を再利用し、切り替え中と
失敗した変更を扱ってください。ブラウザーの選択を保存し、起動時にサーバーと同期してください。
再読み込み、サポートされていないサーバーの言語、通信の失敗、複数のタブをテストしてください。
業務の内容の自動翻訳は追加しないでください。

完了の条件アプリとプラグインのテキストが切り替わり、再読み込みしても選択が保たれ、サーバーのフォールバックや通信の失敗が扱われていること。

主な仕組みと実装

以下は、この例での組み込みの領域と、想定される画面の変化です。開発作業を記述したもので、実際のファイル構成はアプリに合わせてください。

組み込みの領域	コードまたは設定の変更	画面と動作の変化
クライアントとサーバーのロケール	リソースとローダーを追加する	利用できる言語がアプリのリソースを反映する
ヘッダーの言語の選択	useAppLocale を使い、切り替えとエラーを扱う	アプリとプラグインのテキストを更新する
起動時の同期とエラーの画面	useSyncServerLocale と固定の理由を使う	わかりやすいフォールバックとともにサーバーの設定を同期する

言語の取得元

Client と Server を登録します。利用できる言語は、アプリの client/locales/index.ts と server/locales/index.ts で宣言されたローダーから来ます。

言語を有効にするには、アプリのリソースとローダーを追加します。プラグインの翻訳だけでは、言語の選択肢に言語は追加されません。

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 の間は繰り返しの変更を無効にし、reject を処理します。

切り替えでは、名前空間のリソースを読み込み、画面と HTML の言語と方向を更新し、ブラウザーの設定を保存して、サーバーと同期します。プラグインはランタイムを共有し、変更に追従します。

AI 開発の制約と検証

プラグイン固有の開発の制約

選択肢は、ハードコードした別の一覧ではなく、アプリのローダーから導いてください。
setLocale の失敗を扱ってください。サーバーのフォールバックは、ブラウザーの選択が元に戻ったことを意味しません。
欠けているテキスト、再読み込み後の保存、セッションを共有するタブ、サーバーのエラーを確認してください。型チェックではロケールの網羅性は確認できません。

境界

セッションを共有するタブはそのサーバーのロケールも共有するため、別のタブのリクエストが、その画面より先に言語を変えることがあります。必要に応じて、固定の error.reason の値からローカライズしたエラーをレンダリングします。

このプラグインは、業務の内容を自動で翻訳したり、翻訳の管理画面を提供したりはしません。クライアントの多言語化とサーバーの多言語化を参照してください。

これらはあなたの組み込みの検収の要件であり、実機での検証が完了したことを示すものではありません。実際の変更、実行したチェック、未検証の項目をエージェントに報告させてください。プロジェクトのガイダンス、スキル、共通のチェックについてはアプリの開発を続けるとテストを参照してください。

出典：公開のプラグインの入口と実装。

機能