nginx-proxy-manager 前端国际化i18n完全指南从翻译维护、新增语言到自动化校验【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-managernginx-proxy-manager 的管理界面frontend/基于 React react-intl 构建了一套完整的前端国际化体系所有界面文案以带 ID 的消息形式存放在frontend/src/locale/src/下的语言 JSON 中经 formatjs 编译后由运行时加载并配套了帮助文档多语言与自动化校验脚本。本文以 frontend/src/locale/README.md 为主线结合 IntlProvider.tsx、check-locales.cjs、package.json 等源码完整讲解如何启动本地开发栈、添加/编译翻译、从零接入一种全新语言以及如何用脚本保证所有语言文件的键完整性与一致性读完即可独立为该项目维护或扩展多语言支持。一、国际化整体架构与目录约定在深入操作之前先厘清frontend/src/locale/的目录职责这决定了后续每一步改动的位置路径作用frontend/src/locale/src/*.json各语言的源翻译文件含消息 ID 与默认文案是唯一需要人工编辑的翻译载体frontend/src/locale/src/lang-list.json语言名称表键形如locale-en-US值为该语言的本地化名称用于语言选择器展示frontend/src/locale/lang/编译产物由yarn locale-compile从src/生成运行时 import 的是这里见 IntlProvider.tsx 的import langZh from ./lang/zh.jsonfrontend/src/locale/src/HelpDoc/lang/每门语言的帮助文档Markdown index.ts聚合模块为界面各功能页提供多语言使用说明frontend/src/locale/IntlProvider.tsxreact-intl 运行时语言注册表、消息加载、切换逻辑与T翻译组件frontend/src/locale/Utils.ts面向 i18n 的日期时间格式化工具frontend/check-locales.cjs校验脚本检查语言名、缺失键、未使用键与跨语言一致性frontend/src/locale/scripts/locale-sort.sh基于 jq 的 JSON 按键排序脚本保证语言文件格式统一当前仓库内置了 24 种语言en、de、es、et、pt、fr、ga、ja、it、nl、pl、ru、sk、cs、vi、zh、ko、bg、id、tr、hu、no、uk、az。语言注册表定义在 IntlProvider.tsx 的localeOptions数组中每个条目为[语言码, 地区码, 编译后的消息对象]三元组例如[zh, zh-CN, langZh]、[pt, pt-PT, langPt]。注意注释中的约定数组第一项是语言码而非国家码语言码用于匹配地区码用于Intl的 locale 标识与国旗展示。二、开发环境准备启动本地开发栈官方 README 强烈建议在具备 Docker 的服务器上先启动一个开发实例这是翻译工作的第一步git clone 仓库地址 cd nginx-proxy-manager ./scripts/start-dev -f等待一段时间后浏览器访问http://yourserverip:3081即可看到开发版管理界面。该开发栈具备两个对翻译工作至关重要的能力文件监听与热重载开发栈会监视文件系统变化尤其是语言文件保存后浏览器中已打开的页面会自动刷新免去手动重启。自动排序开发栈运行期间保存语言文件时会自动执行按键排序使新增键插入到正确位置、diff 更干净。排序逻辑对应 locale-sort.sh遍历src/下除lang-list.json外的所有 JSON用jq --tab --sort-keys .重新生成未排序文件会被自动修正并提示Sorting file该脚本依赖系统安装jq若缺失会直接报错退出。三、添加新翻译编辑源文件并遵循既有约定新增或修改文案时直接编辑frontend/src/locale/src/下的语言 JSON 文件即可无需触碰lang/编译产物。需要遵循的约定包括键即消息 ID翻译文件是扁平的键值映射键名需与代码中intl.formatMessage({ id })或T组件使用的 ID 完全一致。以英文为基准其他语言文件必须持有相同键集。带参数的动态文案react-intl 支持{name}占位符插值翻译时保留占位符、仅翻译包围文本。保持文件已排序若不在开发栈中编辑可在保存后手动运行yarn locale-sort内部调用locale-sort.sh保持格式统一。提取代码中的全部消息键frontend/package.json提供了基于 formatjs/cli 的两个核心命令package.jsonlocale-extract: formatjs extract src/**/*.tsx, locale-compile: formatjs compile-folder src/locale/src src/locale/langyarn locale-extract扫描src/下所有.tsx文件提取代码中实际使用的翻译 ID输出为临时 JSON。它是check-locales.cjs判定代码在用哪些键的依据。yarn locale-compile把src/locale/src中的源 JSON 编译为src/locale/lang下的运行时 JSON。四、非开发栈环境手动编译翻译如果没有运行开发栈则必须在frontend目录下手动执行编译新翻译才会进入运行时加载的lang目录cd frontend yarn locale-compile编译后frontend/src/locale/lang/下的 JSON 会被重新生成IntlProvider.tsx 顶部静态import的这些文件即随之更新。需要说明的是源语言文件编辑与编译是两步操作跳过编译直接改src/在非开发环境下不会生效开发栈之所以保存即生效正是因为它在内部替你完成了编译与重载。五、添加一门全新语言需要触碰的完整文件清单README 给出了一个可能随时间不完整的清单结合当前仓库源码逐一说明每处改动的内容与位置1. 新建源翻译文件frontend/src/locale/src/[yourlang].json以语言码命名如新增土耳其语则是现有tr.json的模式内容为{ 消息ID: 翻译文本 }的扁平映射。可先复制英文文件作为骨架再整体翻译以保证键集完整。2. 注册语言名称frontend/src/locale/src/lang-list.json在 lang-list.json 中加入形如locale-xx-XX: { defaultMessage: 语言本地化名称 }的条目键必须与localeOptions中的地区码第二项拼接locale-前缀一致例如中文是locale-zh-CN、葡萄牙语是locale-pt-PT。该表同时被语言选择器与校验脚本使用。3. 添加帮助文档目录frontend/src/locale/src/HelpDoc/[yourlang]/*每个语言目录参考 HelpDoc/en包含 6 个 Markdown 文档与一个index.tsAccessLists.md、Certificates.md、DeadHosts.md、ProxyHosts.md、RedirectionHosts.md、Streams.md分别对应访问列表、证书、404 主机、代理主机、重定向主机、TCP/UDP 流六大功能页的帮助内容index.ts聚合导出上述 Markdown 的default字符串。聚合模块 HelpDoc/index.ts 会统一import * as xx from ./xx/index并把新语言加入items对象其getHelpFile(lang, section)提供英文回退逻辑当请求语言或区块缺失时自动回落到en对应文档避免界面帮助面板出现空白README 中写的是index.tsx当前仓库实际文件为index.ts改动时以仓库现状为准。4. 注册运行时语言frontend/src/locale/IntlProvider.tsx在 IntlProvider.tsx 顶部新增对应语言的 import例如import langXx from ./lang/xx.json并在localeOptions数组中加入[xx, xx-XX, langXx]。需要理解其背后的加载逻辑loadMessages(locale)L58-L67取语言码前两位若为en或未注册则回退到英文否则按en → 目标语言的顺序合并消息Object.assign({}, langList, langEn, target)确保新语言缺失的键由英文兜底getFlagCodeForLocaleL69-L88为国旗图标计算 ISO 国家码多数语言直接用语言码大写即可但ja→jp、zh→cn、vi→vn、ko→kr、cs→cz、ga→ie、et→ee、uk→ua这 8 个特例需要显式映射语言码与国旗国家码不一致时务必在此登记否则国旗图标会显示错误。5. 同步校验脚本frontend/check-locales.cjscheck-locales.cjs 顶部维护了一份与localeOptions几乎一致的语言表含英文共 24 个[语言码, 地区码]二元组。新增语言后必须在此追加一行否则脚本会因无法加载该语言文件而漏检。IntlProvider.tsx源码注释也明确提醒添加到此列表时请同步更新 check-locales.js 脚本。完整流程可概括为新建源 JSON → 注册lang-list.json名称 → 新建 HelpDoc 目录与index.ts→ 在IntlProvider.tsximport 并注册localeOptions→ 同步check-locales.cjs列表 → 运行校验与编译。六、检查缺失翻译check-locales.cjs的校验逻辑在frontend目录下执行node check-locales.cjs脚本会依次做四件事源码注释见 check-locales.cjs语言名存在性校验确认每个语言的locale-xx-XX条目存在于lang-list.json缺失则报ERROR: ... does not exist in lang-list.json缺键校验运行yarn locale-extract提取代码中实际使用的全部消息 ID逐语言检查是否覆盖任何在代码中被引用但语言文件中缺失的键都会报 ERROR未使用键校验反向检查语言文件中是否存在代码未使用、且不属于后端错误消息的冗余键避免翻译文件携带死数据跨语言缺失警告汇总所有语言出现的键对缺失某些键的语言输出 WARN黄色提示该语言翻译尚未完整。脚本的退出码有明确语义只要存在 ERROR 即以退出码 1 结束并打印Locale check passed绿色仅当无任何 ERROR 时打印WARN 不阻断流程仅作提示。从源码结构看脚本还预留了后端错误消息error.*的校验位L44-L60当前该段被注释掉意味着前端语言文件同步覆盖后端错误文案这一能力是预留接口而非现行检查项。七、运行时语言切换与日期本地化源码侧佐证理解运行时机制有助于翻译工作者判断改动何时生效、如何验证语言来源优先级getLocale 依次读取localStorage.getItem(locale)→document.documentElement.lang→ 兜底en即用户上次选择会被持久化到 localStorage切换动作changeLocale 重新createIntl并同时写入 localStorage 与html lang属性前端路由页面随即以新 locale 重新渲染翻译组件TL119-L146渲染span contenteditable="false">【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考