詞彙表
詞彙表確保了所有翻譯中產品術語的一致性。使用者可以在一種或多種語言中定義術語的翻譯,讓 AI 模型使用這個預先定義的翻譯,而不是自行選擇。它也可以用於在翻譯成其他語言時,保持某些術語(例如產品名稱)不變。
系統會將兩種指引傳送給模型:
- 術語列於
glossary.userGlossary中(針對文件、JSON 和 SVG,亦包含來自每個ui區塊的現有 UI 翻譯,且uiGlossary保持開啟)。僅當該來源術語出現在正在翻譯的文字中時,才會納入該列。 - 專案內容檔案於
glossary.contextFiles中。完整的專案簡述會注入至每個 UI、文件、JSON、SVG 和校對提示中。該區段位於下方。
術語表的運作方式
術語的來源
| 來源 | 設定 | 使用於 |
|---|---|---|
| UI 目錄 | ui[].uiGlossary(布林值,預設為 true)— 該區塊的 stringsJson | translate-docs、translate-json、translate-svg |
| 使用者 CSV | glossary.userGlossary | translate-ui、proofread-ui、translate-docs、translate-json、translate-svg |
init 將 glossary.userGlossary 指向 glossary-user.csv,且不會建立該檔案。當該檔案遺失時,請執行 glossary-generate,並在第一個 translate-ui 之前將領域術語放入其中。即使是未更改的字串,第二次翻譯也可能產生不同的措辭。詞彙表正是讓兩次執行結果保持一致的關鍵。
具有 uiGlossary: true 的區塊會重複使用已儲存在其 strings.json 中的翻譯作為提示,使文件、JSON 和 SVG 與 UI 保持一致。translate-ui 和 proofread-ui 不會讀取這些目錄 — 它們僅從使用者 CSV 取得提示,因此錯誤的 UI 翻譯不會被回饋為首選術語。對於不應引導其他管線的區塊,請將 uiGlossary 設定為 false。當多個區塊共用同一個來源術語時,較早的區塊會填入某個語言區域,而較晚的區塊僅新增仍然缺少的語言區域。使用者 CSV 的優先順序高於所有 UI 目錄。若某列的 locale 為特定代碼,則會同時取代該語言區域的 * 列和 UI 目錄翻譯。若 locale 為 *,則會將相同的翻譯套用於所有尚未從 UI 目錄取得翻譯的目標語言區域。
精簡的 UI 標籤縮寫(例如結尾帶點的 Alm.,或簡短的單一權杖壓縮如 Size → Tam)仍可用於 UI 翻譯。文件提示會略過它們,因此不會促使模型在 markdown 或 MDX 中產生虛構的 {{…}} 權杖。
當兩個或多個目錄鍵共用一個多詞前綴,且該前綴尚未是鍵時,它會作為其自身的術語添加。對於每個語言環境,翻譯是這些目錄翻譯的共享開頭,在詞語邊界處截斷,並且僅當該共享開頭至少有四個字元時。當兩個德語字串都以 Cursor-Modelle 開頭時,Cursor Models run out 和 Cursor Models at renewal 可以產生 Cursor Models。相同來源的使用者 CSV 列會取代該預設翻譯。
術語傳送的時機
比對不區分大小寫,並在單字邊界(空白或標點符號)停止。系統會優先採用較長的術語,並捨棄重疊的比對結果。當術語與目前批次相符時,提示會收到類似 "dashboard" → "Tableau" 的提示。如果該列具有 Context 註解,則僅針對該比對結果附加此註解。
上下文 是來源語言使用指南(該術語的含義,或如何使用它)。它不是翻譯。更改 上下文 備註或任何 glossary.contextFiles 內容,會在下次執行時重新整理受影響語言環境的快取翻譯 — 您不需要 --force。僅更改非 強制 列上偏好的 翻譯 會保留現有快取,直到您傳遞 --force 或 --force-update。一個 強制 列(新增、編輯或清除)僅針對其來源包含該術語的區段未命中快取,並且僅當儲存的文字尚未包含強制翻譯時。為了這次精確重新整理,請將該列上的 上下文 留空;上下文備註仍然會重新整理整個語言環境。您在儀表板中編輯的列會保持為 user-edited。
Markdown 翻譯會檢查兩到五個字的 UI 標籤,當來源將其引用為整個粗體或行內程式碼範圍、標題或僅為該標籤的行時。包含該術語的較長粗體詞組是提示,因此 **Ask for target language** 不需要 Target language 的目錄形式。單字提示仍可能變形。不是 UI 標籤的使用者 CSV 提示仍是提示。檢查會忽略大小寫,並尋找作為子字串的目錄措辭,因此變形形式仍可能遺漏。它會嘗試下一個模型,直到相同的品質錯誤發生三次或模型清單用盡為止,並且不會因為標籤遺漏而分割區段。如果這些嘗試僅遺漏該檢查,則執行會保留遺漏最少的嘗試,寫入文件,並將區段快取為詞彙表標籤警告。摘要會列出這些警告,且 cacheDir 會收到 glossary-review-*.md,這是您可以貼到 AI 的提示,以將每個遺漏標記為誤報或實際遺漏。當唯一的問題是該警告時,結束代碼仍為 0。
可以在專案設定中透過 glossary.labelCheckSkips 跳過誤報 (儀表板的「詞彙表」分頁會編輯相同的清單)。每個項目都會命名英文 term、要跳過的 locales (* 表示所有地區設定),以及選用的 files 萬用字元。該術語仍是提示。--recheck-glossary-warnings 會再次翻譯已標記的區段,並在檢查通過時清除標記。--force 會與所有其他區段一起重新翻譯它們。處理檔案時會重新檢查快取的 Markdown (--force-update);檔案追蹤跳過的檔案會保持原樣,直到該檔案中的 Force 術語從輸出中遺失,或直到 --recheck-glossary-warnings 開啟包含已標記區段的檔案為止。只要引用該標籤,就需要與來源不同的目錄翻譯,包括翻譯後的產品名稱。使用翻譯等於來源的 Force 列保留來源拼寫。
強制
當 Force 為 true、yes 或 1 時,來源術語會在模型讀取前從文字中移除,並在之後寫回偏好翻譯。用詞會完全一致,而非僅供建議。同樣適用單字邊界和最長比對規則。當模型應優先使用該翻譯但仍可對其進行詞形變化時,請將 Force 留空(或設為 false)。
產生術語表
glossary-generate 會寫入帶有標準標頭的空白 CSV。它會使用設定中的 glossary.userGlossary,或在未設定該金鑰時使用 glossary-user.csv。它會拒絕覆寫已存在的檔案(結束 1)。
ai-i18n-tools glossary-generate
# or: ai-i18n-tools glossary-generate -o i18n/glossary.csv將設定指向該檔案:
{
"glossary": {
"userGlossary": "i18n/glossary.csv"
}
}您也可以直接從儀表板建立 CSV 術語表檔案。在 術語表 索引標籤上首次執行 新增 動作時,如果已指定 glossary.userGlossary 且檔案尚不存在,系統便會建立該檔案。當 glossary.autoAddUserEditedToGlossary 為 true(預設值)時,在儀表板中修正 UI 字串,即可在下次執行 translate-ui 時將該變更新增至 CSV。儀表板也可作為 CSV 術語表的編輯器,讓您在 UI 中新增、編輯或篩選列。
CSV 欄位
標頭列:
Original language string,locale,Translation,Force,Contexten 或 English 可取代 Original language string。Notes 可取代 Context。
| 欄位 | 意義 |
|---|---|
| 原始語言字串 | 來源語言區域中的來源術語或片語 |
| 語言區域 | 目標語言區域代碼,或適用於所有目標的 * |
| 翻譯 | 首選翻譯 |
| 強制 | 設為 true、yes 或 1 以強制使用此措辭;否則僅作為提示 |
| 上下文 | 選用的來源語言說明。僅在此術語相符時傳送 |
範例
每個語言區域一個產品術語、一個強制的德文標籤,以及一個解釋模型可能會照字面理解的詞語的法文資料列:
"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"結合專案簡報:
{
"glossary": {
"userGlossary": "i18n/glossary.csv",
"contextFiles": ["i18n/product-context.md"],
"contextMaxChars": 12000
}
}欄位參考:設定中的 glossary。命令參考:glossary-generate。
專案上下文檔案
glossary.contextFiles 用於不屬於單一 CSV 列的產品級指南:產品是什麼、目標對象是誰、語氣,以及容易誤譯的術語。將設定指向一個或多個相對於 cwd 的 .md / .txt 檔案;它們會按列出順序串接,並注入到每個 UI、文件、JSON、SVG 和校對提示中。
{
"glossary": {
"userGlossary": "i18n/glossary.csv",
"contextFiles": ["i18n/product-context.md"]
}
}以來源語言撰寫簡介,長度應遠低於 glossary.contextMaxChars(預設為 12000),並將其儲存在 docs[].contentPaths 之外,除非您也希望翻譯該檔案。請參閱設定中的 glossary。
使用 AI 代理程式產生上下文檔案
要求代理(Cursor、Claude Code、Copilot 等)讀取儲存庫並撰寫簡介。貼上類似以下的提示:
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-* 執行前檢視該檔案。變更該檔案會使該次執行中每個語言地區的快取翻譯失效,因此一旦品質良好,請保持簡介穩定。