コンテンツにスキップ

国際化

Adaptive Learnerはv1.13.0 / Phase 26以降、8言語（DE、EN、ES、FR、EL、PT、TR、JA）に完全翻訳されて提供されています。プロジェクトのルールとして、ドイツ語コンテンツは実際のウムラウト（ä、ö、ü、ß）を使用します — ASCIIフォールドされたドイツ語はde.yamlとdocs/help/de/**では禁止されています。test_i18n_translation_audit.pyは、ウムラウトのカバレッジと以前のパススルーカタログの≥90%乖離しきい値の両方を固定します。

文字列の場所

バックエンド

backend/config/i18n/{lang}.yaml内のYAMLカタログ — 言語ごとに1ファイル。リファレンスカタログはEN; 他のすべてのカタログは同じキーツリーを持たなければなりません。

# backend/config/i18n/en.yaml
common:
  save: Save
  cancel: Cancel
settings:
  title: Settings
  section_language: Language
  ...

バックエンドはGET /api/i18n/{lang}を公開し、要求された言語のカタログ全体をJSONとして返します。フロントエンドのuseI18nフックが最初のペイント時に呼び出し、結果をキャッシュします。

フロントエンドフォールバック

frontend/src/i18n/fallbacks.tsはフロントエンドバンドルにハードコードされた文字列のインラインサブセットを保持します。これらはバックエンドカタログが読み込まれる前の最初のペイント時に表示されます — そしてカタログエンドポイントが5xxを返した場合の永続的なフォールバックとしても機能します。

useI18nでのフォールバック解決チェーン:

  1. バックエンドカタログ（/api/i18n/{lang}からのライブ文字列）。ドット記法パスを辿ります。
  2. ハードコードされたフロントエンドフォールバック（最初のペイントの復元力）。
  3. 呼び出し元が提供するフォールバック文字列。
  4. キー自体。

アプリ内ヘルプ / ドキュメントサイト

docs/help/_meta.yamlはエントリごとのDE + ENタイトルを持つナビゲーションツリーを宣言します。アプリ内ヘルプパネルはそれを直接読み取り、scripts/generate_mkdocs_nav.pyが同じソースからmkdocs.ymlのnavブロックを再生成します。

ヘルプページのMarkdownはdocs/help/{lang}/...に置かれます — 言語ごとに1つのフォルダ。mkdocs-static-i18nのdocs_structure: folderモードが解決を処理します。

新しい言語の追加

  1. バックエンドカタログ: backend/config/i18n/en.yamlをbackend/config/i18n/{newlang}.yamlにコピーします。すべての値をネイティブに翻訳します（ENパススルーなし — 翻訳監査テストは<90%の乖離で失敗します）。次にmake sync-i18nを実行して、カタログをfrontend/src/data/i18n/{newlang}.jsonにミラーリングします（v1.16.0のホットフィックスで最初のペイントに対して耐性を持つようになったDexieモードバンドル）。
  2. フロントエンド定数: frontend/src/lib/constants.tsのSUPPORTED_LANGUAGESに言語コードを追加します。
  3. フロントエンドフォールバック: 最初のペイントのコードパスが使用する文字列の小さなサブセットを含む{newlang}: {...}ブロックをfrontend/src/i18n/fallbacks.tsに追加します。
  4. 評価質問: plugins/adaptive-learner-plugin-assessment/adaptive_learner_assessment/questions.pyを編集します — すべてのQUESTIONSエントリとすべての回答にtext_{newlang}フィールドを追加します。JSONを再エクスポートします: poetry run python plugins/.../questions.py --export-json frontend/src/data/assessment-questions.json（このようなCLIはまだ存在しません; scripts/のスクリプトには小さな追加が必要です）。
  5. セッションプロンプト: plugins/adaptive-learner-plugin-session/adaptive_learner_session/prompts.pyを編集して、すべての（method, step）セルに3番目の言語キーを追加します。同じ方法でJSONを再エクスポートします。
  6. ドキュメントサイト: mkdocs.ymlのplugins.i18n.languagesブロックを更新し、EN構造をミラーリングしたdocs/help/{newlang}/ディレクトリを追加します。

パリティテスト

backend/tests/test_i18n_parity.pyはすべてのカタログを検証し、以下を確認します。

  • すべての言語がリファレンス（EN）が持つすべてのキーを持っています。
  • どの言語もリファレンスが持たない余分なキーを持っていません。

これは最も一般的なドリフトバグを捉えます: ENにキーを追加して他の7つのファイルに追加するのを忘れること。カタログを変更した後はmake test-backendを実行してください。

複数形

現在のカタログはICU複数形構文を使用していません。レンダリングする数のうち、いくつか（セッション数、ストリーク日数）はTSで形式選択がハードコードされています。

const label = count === 1 ? t("session_single") : t("session_plural");

mkdocs-i18nまたはランタイムICUライブラリを介したICU複数形文字列は延期リストに載っています。

RTL言語

アラビア語、ヘブライ語、ペルシア語などは、CSSで双方向レイアウトサポートが必要です。現在のテーマはLTRを前提としています; RTLの追加は延期リストに載っています。

文字列を追加しない場合

開発者向けのサーフェス（AdaptiveLearnerErrorがスローするエラーメッセージ、ログ行、テストフィクスチャデータ）にのみ表示される文字列は、英語のままにしてください。i18nの機構はエンドユーザーに見える文字列のためだけです。

フロントエンドのconsole.warnとconsole.error呼び出しも英語のままです — これらはブラウザコンソールを読む開発者向けであり、エンドユーザー向けではありません。