アプリの文言は client/locales/ で整理し、既存の翻訳と言語切り替えの仕組みを再利用します。メニュー、フォーム、空の状態、エラーは、同じロケールに従うべきです。見た目については テーマとスタイル を参照してください。
このガイドは、入門のサンプルで使われている既定のテンプレート 1.0.0-beta.81 に沿っています。projects は新しい業務の文言の例です。既定の言語と、ユーザーがすでに保存した設定を区別します。
エージェントを使う場合
プロジェクト機能の英語と中国語の文言をそろえてください。
メニュー、ボタン、フィールドのヒント、空の状態、成功とエラーのフィードバックを網羅し、翻訳キーが画面に見えないようにしてください。
数値と日付は現在の言語に合わせて書式化し、保存された値や業務上のタイムゾーンのルールは変えないでください。
既存の言語の切り替えを再利用し、ユーザーが保存した設定を保持し、新しいブラウザーのコンテキストで既定の動作を確認してください。
アプリで両方の言語を確認し、検証できなかったことを報告してください。エージェントを使わない場合
文言はアプリのロケールファイルに置く
| 場所 | 役割 |
|---|---|
client/locales/en-US.ts | アプリの英語の文言と AppResource 型 |
client/locales/zh-CN.ts | 同じリソース構造を使う、対応する中国語の文言 |
client/locales/system/ | テンプレートのアップグレードとともに管理されるテンプレートの文言 |
client/locales/index.ts | ブラウザーのロケールとそのローダー |
server/locales/ | サーバーが生成するテキストとロケールのローダー |
業務の文言は、projects などのグループに分けてアプリのファイルに追加します。system/ には入れないでください。navigation や actions などの既存の共有グループを拡張するときは、テンプレートのキーを使えるよう、先に既存のものを展開してから拡張します。
たとえば、両方のロケールファイルに次の件数のメッセージを含む projects グループを追加します。グループがすでにある場合は、ほかの内容を置き換えずにこれらのキーを追加します。
// client/locales/en-US.ts — inside projects
count_one: '{{count}} project',
count_other: '{{count}} projects',// client/locales/zh-CN.ts — inside projects
count_one: '{{count}} 个项目',
count_other: '{{count}} 个项目',アプリの翻訳フックを使います。
import { useTranslation } from '@nocobase/i18n/client';
export function ProjectCount({ count }: { count: number }) {
const { t } = useTranslation();
return <span>{t('projects.count', { count })}</span>;
}作成の確認メッセージのような完全な文には、単語を連結するのではなく補間を使います。「保存」や「キャンセル」は共有のキーを再利用し、機能固有の成功とエラーは、ほかのページに影響しないようその機能のグループに置きます。
ロケールの型はリソースの構造を確認しますが、t('projects.titel') を TypeScript が検出できるとは限りません。文言の網羅性のテストを実行し、ブラウザーでも確認してください。
データを書式化し、サーバーの文言を扱う
useLocale() で現在の言語を読み取り、表示する値を Intl.NumberFormat と Intl.DateTimeFormat で書式化します。ロケールによる書式化と業務上のタイムゾーンは別の問題です。言語を切り替えても保存された日付を変更してはならず、日付だけの値が誤ってタイムゾーンをまたぐタイムスタンプになってもいけません。
API のステータスと固定の reason の値をページの文言に対応させ、フィールドのエラーはその入力欄に結び付けます。サーバーの任意の message の値を、そのままユーザー向けの最終的な文言として表示しないでください。サーバーが生成する通知、メールなどのテキストは server/locales/ に置きます。バックグラウンドで生成する内容は、操作した管理者ではなく受信者の言語に従います。
プラグインのテキストの言い回しを変えるには、インストールされたパッケージを編集するのではなく、アプリのロケールリソースでプラグインの名前空間の overrides を使います。内部のキーに依存するのではなく、所有するプラグインのロケールの取り決めを確認してください。
ロケールを追加し、既定を設定する
対応する locales/index.ts に、リソースファイルと動的なローダーを追加します。プラグインに翻訳を追加しただけでは、アプリの言語の選択肢には追加されません。
クライアントとサーバーのロケールの一覧は独立しています。サーバーが生成するテキストにその言語が必要な場合は、サーバーのリソースを追加してから、次を実行します。
pnpm nocobase locales checkこれが確認するのは言語の一覧が一致しているかであり、翻訳が網羅されているかではありません。クライアントだけのロケールもサーバーのフォールバックで動作しますが、この確認では不一致として報告されます。
config.yml で既定を設定します。
i18n:
defaultLocale: zh-CNブラウザーで保存された選択が優先されます。すべてのユーザーの設定を消すのではなく、新しいブラウザーのコンテキストで既定を確認してください。サーバーのセッションがサポートされたブラウザーの選択に従うよう、useSyncServerLocale() は残しておきます。
結果を確認する
この例のロケールの網羅性と型のチェックを実行します。
pnpm exec vitest run tests/client/app-locale-coverage.test.ts
pnpm exec tsc -p tsconfig.json --noEmitブラウザーで両方の言語を確認します。メニュー、空の状態、フィールドのエラー、複数形の件数、日付の書式を含めてください。新しいブラウザーのコンテキストで既定を確認し、既存の保存された設定が引き続き有効であることを確かめます。型チェックは、表示される文言の確認の代わりにはなりません。