開發(fā)工具文檔【免費下載鏈接】typedocDocumentation generator for TypeScript projects.項目地址https://gitcode.com/gh_mirrors/ty/typedoc點擊查看免費下載TypeDoc 自 0.26 版本起為其控制臺輸出和生成的 HTML/JSON 文檔提供了完整的國際化i18n支持。本文以官方文檔 site/development/internationalization.md 為主線結合源碼逐層剖析該機制的完整實現(xiàn)如何理解--lang選項的工作方式、如何在locales目錄下編寫一個新的語言文件、buildTranslation/buildIncompleteTranslation背后的類型校驗原理以及第三方插件如何通過聲明合并與addTranslations把自有字符串納入 TypeDoc 的翻譯體系。讀完本文你可以獨立為 TypeDoc 貢獻一個完整或部分的 locale也可以在自己的插件中接入 TypeDoc 的統(tǒng)一國際化方案。一、功能范圍--lang影響哪些輸出國際化能力由--lang選項控制它會同時作用于兩個層面控制臺輸出TypeDoc 運行期間通過Logger打印的 INFO 及以上級別消息加載插件、轉換進度、錯誤與警告統(tǒng)計等生成的 HTML / JSON 輸出渲染進文檔頁面的內置文案。在選項聲明層面lang被定義為一個字符串類型、默認值為en的參數(shù)聲明位置在 src/lib/utils/options/sources/typedoc.ts第 52–57 行options.addDeclaration({ name: lang, help: () i18n.help_lang(), type: ParameterType.String, defaultValue: en, });值得注意的是help: () i18n.help_lang()這句本身就說明了選項的幫助文本也是可翻譯字符串的一部分——TypeDoc 的選項幫助信息同樣走國際化流程。運行時Application在啟動階段把lang選項的值傳給Internationalization實例見 src/lib/application.ts 第 302 行附近this.internationalization.setLocale(this.lang)。Internationalization類位于 src/lib/internationalization/internationalization.ts其核心邏輯非常直觀setLocale(locale: string): void { if (this.loadedLocale ! locale) { const defaultTranslations translations.get(locale) || translations.get(en) || {}; const overrides this.locales.get(locale); setTranslations({ ...defaultTranslations, ...overrides }); this.loadedLocale locale; } }這里體現(xiàn)了兩級合并策略內置語言包translationsMap為基礎運行時通過addTranslations注冊的覆寫this.locales優(yōu)先級更高。若請求的語言不存在則回退到英文——這與文檔中“未提供的字符串自動回退到默認英文”的行為一致。當前倉庫內置了六個語言包在 src/lib/internationalization/internationalization.ts 第 11–18 行注冊const translations new Mapstring, Recordstring, string([ [de, de], [en, en], [fr, fr], [ja, ja], [ko, ko], [zh, zh], ]);對應的源文件位于 src/lib/internationalization/locales/ 目錄de.ts、en.ts、fr.ts、ja.ts、ko.ts、zh.ts。以 src/lib/internationalization/locales/zh.ts 為例可以看到一個真實的未完成的中文翻譯文件長什么樣// Please DO NOT include machine generated translations here. // If adding a new key, leave it commented out for a native speaker // to update. import { buildIncompleteTranslation } from ../locale-utils.ts; export default buildIncompleteTranslation({ loaded_multiple_times_0: TypeDoc 已加載多次。這通常是由具有自己的 TypeDoc 安裝的插件引起的。加載的路徑為\n{0}, unsupported_ts_version_0: 您正在使用不受支持的 TypeScript 版本運行如果 TypeDoc 崩潰這就是原因。TypeDoc 支持 {0}, no_compiler_options_set: 未設置編譯器選項。這可能意味著 TypeDoc 沒有找到你的 tsconfig.json。生成的文檔可能為空, // ……共 576 行僅覆蓋部分鍵 });二、添加一個新 Locale完整步驟官方文檔給出了添加新語言的標準流程這里完整繼承并結合源碼補充細節(jié)。2.1 文件位置與模板新語言文件應放在src/lib/internationalization/locales/目錄下。英文默認語言的字符串定義在該目錄的en.ts中而 src/lib/internationalization/translatable.ts 負責基于英文字符串推導類型約束詳見第三節(jié)。一個最小可用的新語言文件如下文檔原文示例// zh.cts import { buildTranslation } from ../translatable; export buildTranslation({ docs_generated_at_0: 文檔生成于 {0}, });需要說明兩個實際細節(jié)示例中使用export 是 CommonJS 風格的寫法.cts倉庫中現(xiàn)有的zh.ts等文件使用export default buildIncompleteTranslation({...})的 ESM 風格兩者在構建流程中等價示例中的docs_generated_at_0對應文檔頁腳“文檔生成于 {日期}”這類內置文案。2.2buildTranslation與buildIncompleteTranslation的取舍兩個構建函數(shù)定義在 src/lib/internationalization/locale-utils.tsexport function buildTranslationconst T extends BuiltinTranslatableStringConstraints( translations: T, ) { return translations; } export function buildIncompleteTranslation const T extends PartialBuiltinTranslatableStringConstraints, (translations: T) { return translations; }從源碼結構看這兩個函數(shù)本身只是恒等返回真正的約束全部發(fā)生在類型參數(shù)上buildTranslation要求參數(shù)滿足BuiltinTranslatableStringConstraints——即必須覆蓋所有內置翻譯鍵且每個鍵的占位符數(shù)量正確。提交不完整翻譯時buildTranslation會直接報編譯錯誤缺失屬性。這正對應文檔中的說法“This will give a compiler error onbuildTranslationsince the translation object does not provide a translation for every string supported by TypeDoc.”buildIncompleteTranslation的參數(shù)類型是Partial...允許只翻譯一部分鍵。文檔明確建議如果提交 PR 時翻譯尚未完成應改用buildIncompleteTranslation不完整的翻譯同樣非常受歡迎。2.3 占位符Placeholder格式約定這是翻譯工作中最容易出錯的部分文檔的核心約定可以概括為兩條鍵名內嵌占位符序號翻譯鍵的命名會包含數(shù)字后綴來標示占位符數(shù)量。例如docs_generated_at_0表示該字符串有 1 個占位符_0found_0_errors_and_1_warnings有 2 個_0與_1。這一約定類似 TypeScript 自身錯誤碼的命名習慣其目的正是讓翻譯者在編輯時就知道應寫入多少個{n}。翻譯值中寫{n}占位翻譯字符串中應在占位符出現(xiàn)的位置寫{0}、{1}……運行時代替填充。運行時替換邏輯在 src/lib/utils-common/i18n.ts 第 26–38 行i18n是一個 Proxyexport const i18n new Proxy({}, { get(_, key) { return (...args: string[]) { const template String(translations[key] || key); return template.replace(/\{(\d)\}/g, (_, index) { return args[index] ?? (no placeholder); }); }; }, has(_, key) { return Object.prototype.hasOwnProperty.call(translations, key); }, }) as TranslationProxy;從這段實現(xiàn)可以讀出三個事實未翻譯的鍵會回退為鍵名本身translations[key] || key而不是崩潰占位符按正則/\{(\d)\}/g匹配并用位置參數(shù)填充若參數(shù)數(shù)量不足缺失位置會渲染為字面量(no placeholder)這是一種可觀察的失敗信號方便本地化缺陷在頁面中被發(fā)現(xiàn)。此外i18n對象還導出了TranslatedString類型string { [TranslatedString]: true }和translateTagName函數(shù)。后者負責把param這類注釋標簽名翻譯為對應的tag_*鍵在英文中則按首字母大寫規(guī)則生成標題形式的標簽名——這意味著每個文檔注釋標簽名summary、remarks、defaultValue……也有獨立的翻譯條目這些tag_*鍵由 translatable.ts 中的類型推導自動并入TranslatableStrings。2.4 關于機器翻譯的明確警告官方文檔中有一段重要的IMPORTANT提示值得原樣強調請勿提交你并不熟悉的語言的機器生成翻譯。TypeDoc 依賴貢獻者來保證所收錄翻譯的準確性。這一點在 zh.ts 文件頭部也以英文注釋的形式重申“Please DO NOT include machine generated translations here. If adding a new key, leave it commented out for a native speaker to update.”。參與本地化的正確姿勢是母語者貢獻 缺失鍵保持注釋狀態(tài)等待補全。三、校驗機制編譯期與測試期的雙重保障官方文檔在 “Validation” 一節(jié)說明了buildTranslation與buildIncompleteTranslation會校驗占位符數(shù)量與默認語言一致。這一承諾在源碼中由一套精巧的類型體操兌現(xiàn)全部位于 src/lib/internationalization/translatable.ts從英文字符串推導參數(shù)元組。BuildTranslationArguments遞歸匹配字符串字面量中的{n}片段把每個占位符收集為元組元素type BuildTranslationArgumentsT extends string, Acc extends any[] [] T extends ${string}{${bigint}}${infer R} ? BuildTranslationArgumentsR, [...Acc, string] : Acc;因此BuiltinTranslatableStringArgs中每個鍵對應的類型是一個精確長度的元組0 個占位符即[]1 個即[string]。從參數(shù)數(shù)量生成字符串約束。BuildConstraint遞歸構造形如string{0}string{1}...的模板類型TranslationConstraint是預計算的 0–5 個占位符約束數(shù)組。也就是說一個名為xxx_0的鍵其值必須匹配string{0}string這樣的模式否則translatable satisfies {...}處的編譯器檢查translatable.ts 第 61–65 行會報錯。拒絕未知鍵與多余鍵。文檔指出如果按示例直接把全新對象字面量傳給構建函數(shù)函數(shù)還能校驗翻譯沒有提供默認語言中不存在的鍵——因為參數(shù)類型是satisfies風格約束到BuiltinTranslatableStringConstraints的精確鍵集合多出來的鍵無法通過類型檢查。文檔也如實交代了這套靜態(tài)校驗的邊界“這可以檢查字符串是否漏掉占位符但無法發(fā)現(xiàn)使用了 TypeDoc 不會定義的占位符例如寫成了{9}而實際只傳了 2 個參數(shù)”。這類問題由單元測試兜底——例如 src/test/slow/internationalization-usage.test.ts 會遍歷英文默認語言包中的每一個鍵通過 TypeScript 語言服務的引用分析斷言該鍵確實在代碼中被引用排除其他 locale 文件與 translatable.ts 自身未使用的鍵會讓測試失敗。這保證了默認語言包不會積累死鍵各語言翻譯始終與英文鍵集同步。四、翻譯插件自定義字符串這是文檔的第二大主題插件如何使用 TypeDoc 的國際化模塊為插件自己聲明的字符串提供翻譯。4.1 聲明合并擴展TranslatableStringsaddTranslations要求所有可翻譯字符串都已在TranslatableStrings接口中聲明。該接口定義在 internationalization.ts 第 55 行本身就繼承了內置字符串的類型export interface TranslatableStrings extends BuiltinTranslatableStringArgs {}其 JSDoc 明確寫道“Plugins may use declaration merging to add members to this interface to use TypeDocs internationalization module.” 插件側按文檔給出的標準寫法操作以下示例完整繼承自官方文檔import * as td from typedoc; declare module typedoc { interface TranslatableStrings { // 定義一個無參的可翻譯字符串 plugin_example_hello_world: []; // 定義一個需要一個參數(shù)的可翻譯字符串 // 按約定鍵名應包含每個占位符的索引編號 plugin_example_hello_0: [string]; } } export function load(app: td.Application) { app.internationalization.addTranslations(en, { plugin_example_hello_world: Hello World!, plugin_example_hello_0: Hello {0}!, }); app.logger.info(app.i18n.plugin_example_hello_world()); // 輸出 Hello World! app.logger.info(app.i18n.plugin_example_hello_0(TypeDoc)); // 輸出 Hello TypeDoc! }聲明合并中的元組字面量[]、[string]直接決定了i18n代理上對應函數(shù)的參數(shù)簽名由于TranslationProxy類型是按TranslatableStrings[K]生成的函數(shù)類型見 internationalization.ts 第 60–64 行占位符數(shù)量在插件側同樣享有編譯期保護。4.2 運行時注入與配置文件中覆寫addTranslations的實現(xiàn)internationalization.ts 第 86–91 行做了兩件事把翻譯存入對應 locale 的 map若該 locale 恰好是當前已加載的語言則立即addTranslations進全局翻譯表使新字符串立刻可用。除了插件在load(app)中自行注冊倉庫還為“不寫代碼、只寫配置”的場景提供了locales配置項聲明見 src/lib/utils/options/sources/typedoc.ts 第 58–74 行options.addDeclaration({ name: locales, help: () i18n.help_locales(), type: ParameterType.Mixed, configFileOnly: true, // 只能出現(xiàn)在配置文件不能是命令行參數(shù) defaultValue: {}, // validate: 必須是“l(fā)ocale - 鍵 - 字符串”的嵌套對象 });在 src/lib/application.ts 第 323 行附近Application啟動時會遍歷locales選項的每個條目并調用this.internationalization.addTranslations(lang, locales)。這意味著如果一個插件的字符串你只需要翻譯給自己的項目看不必 fork 插件直接在typedoc.json中寫一個locales字段覆寫即可。同時getSupportedLanguages()會把“注冊了非空覆寫”的語言也計為受支持語言用于hasTranslations的判斷。五、小結與實操清單查看文檔官方指南位于 site/development/internationalization.md插件 API 參考見TranslatableStrings與Internationalization.addTranslations的接口文檔由本倉庫自動生成。為 TypeDoc 增加語言在 src/lib/internationalization/locales/ 新建文件完整的用buildTranslation不完整的用buildIncompleteTranslation見 locale-utils.ts鍵名保留_0/_1后綴翻譯值寫{n}占位符只提交母語級別的翻譯。讓插件字符串可翻譯declare module typedoc聲明合并 app.internationalization.addTranslations(...)用戶側可用typedoc.json的locales字段免代碼覆寫。校驗鏈路編譯期由 translatable.ts 的類型約束保證占位符數(shù)量與鍵集合正確運行期由 i18n.ts 的 Proxy 兜底渲染測試期由 src/test/slow/internationalization-usage.test.ts 保證默認語言包無死鍵。適用前提說明以上分析基于當前倉庫TypeDoc ≥ 0.26 特性集lang選項默認為en內置語言為 de/en/fr/ja/ko/zh如果你的項目鎖定在更早版本國際化相關 API 與本文描述可能不一致請以對應版本的倉庫內容為準。贊分享開發(fā)工具文檔【免費下載鏈接】typedocDocumentation generator for TypeScript projects.項目地址https://gitcode.com/gh_mirrors/ty/typedoc點擊查看免費下載相關推薦Luanti國際化實戰(zhàn)80語言翻譯機制與.po文件本地化完整流程Luanti國際化實戰(zhàn)80語言翻譯機制與.po文件本地化完整流程 Luanti 原名 Minetest是一個開源體素游戲創(chuàng)作平臺其國際化體系讓游戲界面游戲開發(fā)圖形學vue-cli UI 國際化實戰(zhàn)指南翻譯標準 UI 與 Vue CLI 插件的本地化機制vue cli UI 國際化實戰(zhàn)指南翻譯標準 UI 與 Vue CLI 插件的本地化機制 本文圍繞 vue cli 官方文檔《UI 本地化》展開系統(tǒng)講解如何前端開發(fā)工具構建工具Sails 國際化之 config/locales 目錄locale 字符串文件的組織、加載與翻譯實踐Sails 國際化之 config/locales 目錄locale 字符串文件的組織、加載與翻譯實踐 config/locales 目錄是 Sails 應用后端上一篇B站搶票神器跨平臺自動化工具助你告別搶票焦慮下一篇飛書文檔批量導出工具高效遷移700文檔的完整技術方案創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考