Skip to content

CLI — UI 字串 ​

extract ​

概要: ai-i18n-tools extract

從 t("…") / i18n.t("…") 常值、選用的 package.json 描述,以及啟用 includeUiLanguageEnglishNames 時選用的內建主要 englishName 項目來更新 strings.json(請參閱 ui.uiExtractor;不會讀取 languagesManifestPath)。同時重新產生每個區塊的 ui-languages.json。當 ui.uiExtractor.extensions 中列出 .html / .htm 時,也會從 HTML 擷取 data-i18n / data-i18n-title / data-i18n-placeholder 標記字串。遍歷每個具有 sourceRoots 的 ui 區塊。--ui-block 會將執行限制為單一區塊(索引、描述或 stringsJson 路徑)。不會呼叫 LLM。

另請參閱: UI 字串概觀, 純 HTML 應用程式


migrate-intlayer ​

概要: ai-i18n-tools migrate-intlayer [paths...] [--write] [--report <path>] [--content-glob <glob>] [--t-import <specifier>]

將 Intlayer *.content.ts 字典匯入 strings.json 和扁平化語系檔案,並將簡單的 useIntlayer / getIntlayer 呼叫位置重寫為 t('source string')。字串以 sourceLocale 撰寫,可以是任何語言。預設為模擬執行 (仍會寫入報告)。--write 會為目錄植入資料並套用安全的重寫。不會呼叫 LLM。

此報告是 --write 所留下所有內容的交接文件,結尾附有 逐步待辦事項 以安排後續工作:每個手動站點的具體 t() 或 JSX 呼叫、import { t } 行、字典檔與後續需刪除的 IntlayerProvider 殘留檔案、需要先 extract 再 translate-ui 的來源字串,以及用來覆寫應用程式 i18n 模組的 i18next 執行階段啟動程式碼。區域設定控制項必須呼叫 i18n.changeLanguage 與 loadLocale。extract 會寫入 ui-languages.json,並由該啟動程式碼匯入。請勿手動編輯 strings.json、扁平化區域設定檔案或 ui-languages.json。

主要選項: --write, --report, --content-glob (預設 **/*.content.ts), --t-import

另請參閱: 從 Intlayer 遷移


translate-intlayer ​

概要: ai-i18n-tools translate-intlayer [paths...] [-l <codes>] [--ui-block <selector>] [--dry-run] [-j <n>]

就地翻譯 Intlayer *.content.ts 字典中遺失和過時的語系葉節點,並維持字典作為真實來源 (source of truth)。與 migrate-intlayer 不同,此操作不會將應用程式從 Intlayer 移出;它只會填入 t({ … }) 葉節點。當您想在執行階段保留 Intlayer 並使用 ai-i18n-tools 作為翻譯引擎時,請使用此功能。

它提取每個t({ … })葉節點,將原始文字植入所選UI區塊的strings.json中,執行與translate-ui相同的引擎(提供者選擇、詞彙表、翻譯上下文和模型備援),然後將新的每個地區的字串寫回每個t({ … })物件中。編輯精確:僅更改缺失或過時的地區行,因此您的格式和註解得以保留。Intlayer {token}佔位符會往返傳送至{{token}}進行翻譯並返回。

當葉節點中缺少該語系 (遺失),或自上次針對該語系執行後來源語系文字已變更 (過時) 時,就會翻譯「葉節點+語系」。過時狀態會在 cacheDir 中追蹤,因此編輯該來源字串會在下次執行時重新翻譯該葉節點。來源語言為 sourceLocale,可以是任何語言。--dry-run 會報告遺失/過時的計數,而不會呼叫 LLM 或寫入任何內容。需要 features.translateUIStrings 和 UI 區塊的 stringsJson (與 translate-ui 相同)。

主要選項: -l / --locale、--ui-block、--dry-run、-j / --concurrency

[paths...]:要掃描的檔案/目錄/萬用字元模式(預設:區塊的 sourceRoots)。-l / --locale:要填入的逗號分隔目標語言環境(預設:區塊已配置的 targetLocales)。--ui-block:從零開始的索引、描述或 stringsJson 路徑(預設:區塊 0)。-j 平行處理語言環境。

另請參閱: migrate-intlayer、從 Intlayer 遷移


mark-html ​

概要: ai-i18n-tools mark-html [paths...] [--write]

將純 data-i18n / data-i18n-title / data-i18n-placeholder 標記插入 HTML,使來源文字僅寫入一次(在元素本身上)。掃描指定的檔案/目錄/Glob 模式(預設:每個區塊 sourceRoots 下的 .html / .htm)。預設為試執行(回報每個檔案的新增計數,以及任何需要手動 <span data-i18n> 的混合內容元素);--write 會套用變更。具備冪等性、遵循 data-i18n-ignore(跳過該元素及其子樹狀結構)、絕不觸及類似程式碼的元素(code、pre、kbd、samp、var)或空白/純數字文字,且絕不發出帶值的標記。不會呼叫 LLM。

關鍵選項: --write

另請參閱: 標記 HTML 以供翻譯


generate-ui-languages ​

概要: ai-i18n-tools generate-ui-languages [--master <path>] [--dry-run]

使用 sourceLocale + targetLocales 與隨附的 data/ui-languages-complete.json(或 --master)將 ui-languages.json 寫入 languagesManifestPath(預設為 {ui.flatOutputDir}/ui-languages.json)。會針對主檔中缺少的地區設定發出警告並產生 TODO 佔位符。如果您現有的資訊清單包含自訂的 label 或 englishName 值,它們將會被主目錄預設值取代 — 請在之後檢閱並調整產生的檔案。

關鍵選項: --master, --dry-run


translate-ui ​

概要: ai-i18n-tools translate-ui [-l <codes>] [--force] [--dry-run] [-j <n>]

僅翻譯 UI 字串(strings.json → 地區設定 JSON)。需要 features.translateUIStrings。

關鍵選項: -l / --locale, --force, --dry-run, -j / --concurrency

-l / --locale:逗號分隔的目標語言環境(預設值:設定 targetLocales 減去 sourceLocale)。--force:重新翻譯每個語言環境的所有條目(忽略現有翻譯)。--dry-run:不寫入,不進行 API 呼叫。-j 平行處理 語言環境;在每個語言環境中,設定 uiBatchConcurrency(預設值 2)平行處理 LLM 批次(50 個字串的區塊,然後是複數群組)。沒有適用於 uiBatchConcurrency 的 CLI 旗標。每個成功的批次都會寫入 strings.json 和扁平語言環境檔案,然後才開始下一個批次。sync-ui 和 sync 的 UI 步驟使用相同的寫入操作。

已儲存的翻譯,如果其佔位符與來源不符,會再次翻譯。此檢查涵蓋重新命名的名稱 ({schedule} 變為 {cronograma})、遺失或新增的權杖,以及格式規格變更 ({price:,.2f} 變為 {price})。計數會在批次之前列印,包括在 --dry-run 上。模型為 user-edited 的列會保留在原位,且只會發出警告。僅包含佔位符和標點符號的字串 (例如 {state} · {title}) 會被複製,且不會傳送至模型。重新命名佔位符的批次會被拒絕,且會嘗試鏈中的下一個模型,並附加該錯誤。儀表板會標記相同的列,並在儲存破壞佔位符的翻譯之前詢問。


sync-ui ​

概要: ai-i18n-tools sync-ui [-l <codes>] [--force] [--dry-run] [-j <n>]

先擷取,再翻譯 UI 字串(需要 features.translateUIStrings)。僅限 UI — 不含文件、SVG 或 json[]。與 translate-ui 使用相同的 -l、--force、--dry-run 及 -j 選項。


proofread-ui ​

概要: ai-i18n-tools proofread-ui [-l <code>] [--chunk <n>] [--dry-run] [--json] [-j <n>]

首先執行 extract(需要 features.translateUIStrings),以便每個選定的目錄與來源匹配,然後對來源語言環境的 UI 字串進行 LLM 審查(拼寫、語法)。--ui-block 將提取和審查限制為一個區塊。術語提示僅來自 glossary.userGlossary CSV(與 translate-ui 範圍相同 — UI 目錄不會回饋,因此不良文案不會被強化為詞彙表)。使用活動 LLM 供應商(其 API 密鑰環境變數)。

失敗時以 1 結束 (缺少功能旗標、擷取失敗、缺少/無效的目錄、缺少 API 金鑰,或所有批次皆失敗時);執行成功完成時以 0 結束 (發現僅供參考)。將 proofread-ui-results_<timestamp>.log 寫入 cacheDir 下,作為人類可讀的報告 (摘要、問題、未審查的列,以及每個字串的 OK 列);終端機僅列印摘要計數和問題 (每個字串沒有 [ok] 行)。失敗的批次,或是短於批次長度且在每個位置沒有可用 index 的模型回應,會將這些字串計為未審查。系統會捨棄其問題,以免將過短的陣列套用到錯誤的字串。在最後一行印出記錄檔名稱。使用 --json 時,人類風格的輸出會傳送至 stderr。連結會使用 path:line,類似儀表板 UI 字串的連結按鈕。

關鍵選項: -l / --locale、--chunk(預設 50)、--dry-run、--json、-j / --concurrency


export-ui-xliff ​

概要: ai-i18n-tools export-ui-xliff [-l <codes>] [-o <dir>] [--untranslated-only] [--dry-run]

將 strings.json 匯出為 XLIFF 2.0(每個目標語系一個 .xliff)。唯讀;無 API。

關鍵選項: -l / --locale、-o / --output-dir、--untranslated-only、--dry-run

-o / --output-dir:輸出目錄(預設:與目錄相同的資料夾)。--untranslated-only:僅包含該語系缺少翻譯的單元。

採用 MIT 授權條款釋出。