Skip to content

用語集 ​

用語集は、翻訳全体で製品用語の一貫性を確保します。ユーザーは、1つまたは複数の言語で用語の翻訳を定義でき、これによりAIモデルは、自身で選択する代わりに、この事前定義された翻訳を使用できます。また、他の言語への翻訳時に、製品名などの特定の用語を変更せずに維持するためにも使用できます。

モデルには2種類のガイダンスが送信されます。

  • glossary.userGlossary内の用語行(およびドキュメント、JSON、SVGについては、uiGlossaryをオンのままにした各uiブロックからの既存のUI翻訳)。行は、該当するソース用語が翻訳対象テキストに出現する場合にのみ含まれます。
  • glossary.contextFiles内のプロジェクトコンテキストファイル。完全なブリーフは、すべてのUI、ドキュメント、JSON、SVG、および校正プロンプトに注入されます。該当セクションは以下を参照してください。

用語集の仕組み ​

用語の取得元 ​

ソース設定使用元
UIカタログui[].uiGlossary(ブール値、デフォルトはtrue)— そのブロックのstringsJsontranslate-docs、translate-json、translate-svg
ユーザーCSVglossary.userGlossarytranslate-ui、proofread-ui、translate-docs、translate-json、translate-svg

init は glossary.userGlossary を glossary-user.csv に指定しますが、そのファイルは作成しません。そのファイルが存在しない場合は glossary-generate を実行し、最初の translate-ui の前にドメイン用語を記述してください。変更されていない文字列を再度翻訳すると、異なる表現になる可能性があります。用語集を使用することで、2回の実行で一致させることができます。

uiGlossary: trueが設定されたブロックは、そのstrings.jsonにすでに保存されている翻訳をヒントとして再利用するため、ドキュメント、JSON、SVGがUIと整合性を保ちます。translate-uiとproofread-uiはこれらのカタログを読み取らず、ユーザーCSVからのみヒントを取得するため、不適切なUI翻訳が優先用語としてフィードバックされることはありません。他のパイプラインを誘導しないようにするブロックでは、uiGlossaryをfalseに設定します。複数のブロックが1つのソース用語を共有する場合、先行するブロックがロケールを埋め、後続のブロックはまだ不足しているロケールのみを追加します。ユーザーCSVはすべてのUIカタログに優先します。localeが特定のコードである行は、そのロケールにおける*行とUIカタログの翻訳の両方を置き換えます。*のlocaleは、UIカタログからの翻訳がまだ存在しないすべてのターゲットロケールに同じ翻訳を適用します。

簡潔なUIラベル略語(Alm.のような末尾のドット、またはSize → Tamのような短い単一トークン圧縮)は、UI翻訳で引き続き使用できます。ドキュメントプロンプトはこれらをスキップするため、モデルがmarkdownやMDXで{{…}}トークンを勝手に生成する方向に誘導されることはありません。

複数のカタログキーに共通する複数単語のプレフィックスは、そのプレフィックスがまだキーでない場合、それ自体が用語として追加されます。各ロケールでは、翻訳はそれらのカタログ翻訳の共通の開始部分であり、単語の区切りで切り取られ、その共通の開始部分が4文字以上である場合に限られます。両方のドイツ語文字列がCursor-Modelleで始まる場合、Cursor Models run outとCursor Models at renewalはCursor Modelsを生成できます。同じソースに対するユーザーCSV行は、そのシードされた翻訳を置き換えます。

用語が送信されるタイミング ​

マッチングは大文字と小文字を区別せず、単語の境界(空白または句読点)で停止します。長い用語が優先され、重複するマッチは破棄されます。用語が現在のバッチにマッチすると、プロンプトは"dashboard" → "Tableau"のようなヒントを受け取ります。その行にコンテキストノートがある場合、そのノートはそのマッチに対してのみ追加されます。

Contextは、ソース言語での使用ガイダンス(用語の意味や使用方法)です。これは翻訳ではありません。Contextノート、またはglossary.contextFilesコンテンツを変更すると、次回の実行時に影響を受けるロケールのキャッシュされた翻訳が更新されます。--forceは必要ありません。Forceではない行で、優先されるTranslationのみを変更した場合、--forceまたは--force-updateを渡すまで既存のキャッシュが保持されます。Force行(新規、編集済み、またはクリア済み)は、ソースにその用語が含まれるセグメントに対してのみ、また保存されたテキストに強制翻訳がまだ含まれていない場合にのみ、キャッシュミスします。この限定的な更新のために、その行のContextは空のままにしてください。Contextノートは依然としてロケール全体を更新します。ダッシュボードで編集した行はuser-editedとして残ります。

Markdown翻訳は、ソースがそのラベル全体を太字またはインラインコードスパン、見出し、あるいはそのラベルのみの行として引用している場合、2〜5語のUIラベルをチェックします。その用語を含むより長い太字のフレーズはヒントと見なされるため、**Ask for target language**はTarget languageのカタログ形式を必要としません。単語のヒントは、活用形であっても有効な場合があります。UIラベルではないユーザーCSVヒントは、ヒントとして扱われます。チェックでは大文字と小文字を区別せず、カタログの語句を部分文字列として検索するため、活用形でも見落とされる可能性があります。同じ品質エラーが3回発生するか、モデルリストがなくなるまで次のモデルを試行し、ラベルの見落としのためにセグメントを分割しません。これらの試行がそのチェックのみを見落とした場合、実行は最も見落としの少ない試行を保持し、ドキュメントを書き込み、用語集ラベル警告とともにセグメントをキャッシュします。概要にはこれらの警告が一覧表示され、cacheDirはglossary-review-*.mdを受け取ります。これは、各見落としを誤検知または実際の見落としとしてマークするためにAIに貼り付けることができるプロンプトです。唯一の問題がその警告である場合、終了コードは0のままです。

誤検知は、プロジェクト設定でglossary.labelCheckSkipsを使用してスキップできます(ダッシュボードの「用語集」タブで同じリストを編集します)。各エントリには、英語のterm、スキップするlocales(*はすべてのロケールを意味します)、およびオプションのfilesグロブが指定されます。その用語はプロンプトヒントとして残ります。--recheck-glossary-warnings は、フラグ付きセグメントを再翻訳し、チェックが合格した場合にフラグをクリアします。--force は、他のすべてのセグメントと一緒にそれらを再翻訳します。キャッシュされたマークダウンは、ファイルが処理されると再チェックされます(--force-update)。ファイル追跡がスキップするファイルは、そのファイル内のForce用語が出力から欠落するか、--recheck-glossary-warningsがフラグ付きセグメントを持つファイルを開くまで、そのまま残されます。ソースと異なるカタログ翻訳は、翻訳された製品名を含め、そのラベルが引用される場所ではどこでも必要です。翻訳がソースと等しいForce行で、ソースのスペルを保持します。

強制 ​

強制がtrue、yes、または1の場合、ソース用語はモデルがそれを参照する前にテキストから削除され、その後優先翻訳が書き戻されます。文言は提案ではなく正確なものです。同じ単語境界と最長マッチのルールが適用されます。モデルが翻訳を優先しつつも語形変化させる可能性がある場合は、強制を空(またはfalse)にしておきます。

用語集の生成 ​

glossary-generateは、標準ヘッダーを持つ空のCSVを書き込みます。構成からはglossary.userGlossaryを使用し、そのキーが設定されていない場合はglossary-user.csvを使用します。すでに存在するファイルの上書きは拒否されます(終了コード1)。

bash
ai-i18n-tools glossary-generate
# or: ai-i18n-tools glossary-generate -o i18n/glossary.csv

構成でファイルを指定します。

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv"
  }
}

ダッシュボードから直接CSV用語集ファイルを作成することもできます。用語集タブで最初に追加操作を行うと、glossary.userGlossaryが指定されており、かつファイルがまだ存在しない場合にファイルが作成されます。glossary.autoAddUserEditedToGlossaryがtrue(デフォルト)の場合、ダッシュボードでUI文字列を修正すると、次回のtranslate-uiの実行時にその変更内容がCSVに追加されます。ダッシュボードはCSV用語集のエディターとしても機能し、UI内で行の追加、編集、またはフィルタリングが行えます。

CSV列 ​

ヘッダー行:

text
Original language string,locale,Translation,Force,Context

enまたはEnglishはOriginal language stringの代わりに受け入れられます。NotesはContextの代わりに受け入れられます。

列意味
元の言語の文字列ソースロケールでのソース用語またはフレーズ
ロケールターゲットロケールコード、またはすべてのターゲットに対する*
翻訳推奨される翻訳
強制この表記を必須とする場合はtrue、yes、または1を指定。それ以外の場合はヒント
コンテキストオプションのソース言語による説明。この用語が一致した場合にのみ送信されます

例 ​

各ロケールに対する1つの製品用語、強制適用されるドイツ語のラベル、そしてモデルが文字通り解釈してしまう可能性のある単語を説明するフランス語の行:

csv
"Original language string","locale","Translation","Force","Context"
"dashboard","*","Tableau","false","The analytics home, not a vehicle panel"
"Save","de","Speichern","true",""
"workspace","fr","espace de travail","false","A user's project container, not an office"

プロジェクトブリーフと組み合わせた場合:

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md"],
    "contextMaxChars": 12000
  }
}

フィールドリファレンス:設定のglossary。コマンドリファレンス:glossary-generate。

プロジェクトコンテキストファイル ​

glossary.contextFilesは、単一のCSV行には属さないプロダクトレベルのガイダンス用です。プロダクトの内容、対象ユーザー、トーン、誤訳しやすい用語などが含まれます。設定でcwd相対の1つ以上の.md / .txtファイルを指定します。これらは記載順に連結され、すべてのUI、ドキュメント、JSON、SVG、および校正プロンプトに注入されます。

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md"]
  }
}

ブリーフはソースロケールで記述し、glossary.contextMaxChars(デフォルト12000)を大幅に下回るように保ち、そのファイルも翻訳したい場合を除いてdocs[].contentPathsの外に保存してください。設定のglossaryを参照してください。

AIエージェントを使用してコンテキストファイルを生成する ​

エージェント(Cursor、Claude Code、Copilotなど)にリポジトリを読み取らせてブリーフを記述させます。次のようなプロンプトを貼り付けてください。

text
Create a translation-context Markdown file for this repository at i18n/product-context.md.

This file is injected verbatim into every ai-i18n-tools translation prompt (UI strings, docs, JSON, SVG, proofread). It must stay in the source language of the project (do not translate it). Translators already receive a glossary of preferred term mappings; this file should explain meaning, audience, and register — not duplicate every glossary row.

Requirements:
- Concise: aim for 1–4 KB, hard limit 8000 characters. No full manuals, README dumps, or changelog history.
- Source-language only. Short headings, bullet lists, and a few example sentences are enough.
- No secrets, API keys, credentials, personal data, internal URLs, or unpublished commercial figures.
- Do not invent product facts. If something is unclear, omit it or mark it as unknown.
- Do not put this file under a path that is also listed in docs[].contentPaths.

Cover, in this order:
1. Product in one paragraph: what it is, who uses it, and the default tone (formal / informal / technical).
2. Domain and disambiguation: terms that look ordinary in English but have a product-specific meaning (for example “dashboard” as an analytics home, not a vehicle panel).
3. Features or areas that change register (billing vs. onboarding vs. admin).
4. Things translators must preserve exactly: brand names, CLI flags, config keys, code identifiers, placeholder tokens.
5. Locale notes only when they affect meaning for every target (for example “use formal you”). Do not list per-locale translations here.

Write only the Markdown file. Afterward, remind me to add it to glossary.contextFiles in ai-i18n-tools.config.json if it is not already listed.

次回のsync / translate-*実行前にファイルを確認してください。ファイルを変更すると、その実行で各ロケールのキャッシュされた翻訳が無効化されるため、品質が良好になったらブリーフを安定させてください。

MITライセンスの下で公開されています。