Homepage 多语言与国际化Crowdin 社区翻译协作完整指南【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepageHomepage 的界面文本包括所有 Widget 的标签、状态文案与数值格式化全部基于 i18next 国际化体系构建默认语言为英语其余语言均由社区通过 Crowdin 平台协作提供。本文基于 docs/more/translations.md 展开结合仓库中实际的国际化配置、源码实现与测试用例完整讲解如何参与翻译、添加新语言、为 Widget 编写翻译字符串以及语言在运行时的加载与回退机制帮助你在部署和贡献两个层面用好 Homepage 的多语言能力。Homepage 的国际化架构总览Homepage 以英语作为唯一开发语言所有组件与 Widget 的贡献必须使用英文编写界面上的其他语言全部由社区翻译者提供。整个多语言体系在仓库中由几个关键部分共同支撑翻译资源文件所有语言的 JSON 字典位于 public/locales/ 目录每种语言一个子目录内含common.json当前仓库已内置 45 个语言目录含en、zh-Hans、zh-Hant、ja、ko、de、fr等翻译框架使用 next-i18next 库处理翻译应用入口通过appWithTranslation包装见 src/pages/_app.jsx页面在服务端通过serverSideTranslations加载对应语言的字典见 src/pages/index.jsx格式化扩展在 next-i18next.config.js 中注册了bytes、rate、percent、date、relativeDate、duration等自定义格式化器让数值与时间能按当前语言环境正确显示Crowdin 同步配置crowdin.yml 定义了以en为源语言、向各语言目录分发翻译的映射规则。# crowdin.yml —— 源语言 en 与目标语言的映射关系 project_id_env: CROWDIN_PROJECT_ID api_token_env: CROWDIN_PERSONAL_TOKEN preserve_hierarchy: true files: - source: /public/locales/en/*.json translation: /public/locales/%osx_locale%/%original_file_name%%osx_locale%会被 Crowdin 替换为目标语言代码如zh-Hans、fr%original_file_name%保持原文件名如common.jsonpreserve_hierarchy: true保留目录层级。从源码结构看仓库中的 45 个语言目录正是这一同步机制持续产出的结果。如何配置首页显示语言对使用者而言多语言能力通过settings.yaml中的一个顶层配置项开启。在 docs/configs/settings.md 中说明language: fr未设置时默认使用英语en仓库文档列出的当前受支持语言包括ca, de, en, es, fr, he, hr, hu, it, nb-NO, nl, pt, ru, sv, vi, zh-Hans简体、zh-Hant繁体实际上 public/locales/ 下已存在更多语言目录如ja、ko、ar、uk等只要目标语言目录存在即可生效旧配置兼容zh-CN仍然可用会自动映射为zh-Hans也可以指定带区域的 locale如en-AU、en-GB这在日期时间等 Widget 中会影响格式化输出。语言代码规范化zh-CN 到 zh-Hans 的自动映射zh-CN兼容逻辑并非写在文档层面而是有真实的源码实现。在 src/pages/index.jsx 中// Normalize language codes so older config values like zh-CN still point to Crowdin-provided ones const LANGUAGE_ALIASES { zh-cn: zh-Hans, }; const normalizeLanguage (language) { if (!language) return en; const alias LANGUAGE_ALIASES[language.toLowerCase()]; return alias || language; };对应的测试用例位于 src/tests/pages/index.test.jsx验证了当配置写入language: zh-CN时getStaticProps会以zh-Hans请求翻译资源。此外测试还覆盖了两个重要行为正常情况按配置语言加载en以及配置解析出错时回退到英语见同文件 L208-L221。这印证了运行时的兜底策略语言加载失败时不会白屏而是退回默认英文界面。语言在运行时的加载链路从源码可以还原完整的语言加载流程getStaticProps中读取settings.language经normalizeLanguage规范化后调用serverSideTranslations(language)src/pages/index.jsx服务端构建时即把对应语言字典序列化进页面 props页面挂载后Home组件通过useTranslation()拿到i18n实例并在settings.language变化时调用i18n.changeLanguage(language)src/pages/index.jsx所有组件统一通过useTranslation钩子取翻译键渲染如 src/components/quicklaunch.jsx、src/components/services/status.jsx。这意味着修改settings.yaml中的language后重新加载页面即可切换到目标语言界面无需额外操作。参与现有语言的翻译支持翻译如果你希望将 Homepage 翻译成更多语言或改进已有语言的翻译质量官方推荐的流程非常简单全程在 Crowdin 平台上完成在 Crowdin 注册一个免费账号进入 Homepage 翻译项目选择你希望翻译的语言开始逐条翻译字符串。翻译对象即各语言的common.json源语言始终是en。翻译完成后合入的翻译会经由 Crowdin 的同步机制见 crowdin.yml更新回仓库的 public/locales/ 对应语言目录随下一次发布生效。添加一种全新的语言如果目标语言尚未出现在 Homepage 的翻译项目中需要先在 Crowdin 的 Homepage 项目里创建一条 Discussion 提出请求维护者确认后会把新语言添加到项目中之后即可按上述流程开始翻译。需要提醒的是不要直接在仓库中手工新建语言目录。仓库中 public/locales/ 下的语言目录是 Crowdin 同步的产物新增语言的正确入口是 Crowdin 项目直接手工添加的文件既可能被同步覆盖也无法进入后续的翻译维护流程。为 Widget 编写与翻译字符串开发者视角如果你在贡献 Widget 组件其界面上所有文本与数值内容都必须走翻译。完整的开发规范见 docs/widgets/authoring/translations.md核心要点如下。在组件中使用翻译键在component.jsx中通过useTranslation取t函数Block的label直接使用翻译键而不是硬编码文案import { useTranslation } from next-i18next; import Container from components/services/widget/container; import Block from components/services/widget/block; export default function Component() { const { t } useTranslation(); return ( Container service{service} Block labelyourwidget.key1 / Block labelyourwidget.key2 / Block labelyourwidget.key3 / /Container ); }在 common.json 中登记英文翻译打开 public/locales/en/common.json在文件底部为你的 Widget 追加一个对象。以仓库中unifi_drive、duplicati等 Widget 的既有写法为参考新增的英文条目形如yourwidget: { key1: Value 1, key2: Value 2, key3: Value 3 }一个关键约定原文档原文强调即使你的母语不是英语也只提交英文翻译。其他语言的翻译由社区在 Crowdin 上完成——等你贡献的 Widget 合入主线后再通过 Crowdin 补充母语翻译即可。这与组件贡献必须用英文的总体原则保持一致。可复用的通用翻译键Homepage 为所有 Widget 提供了一套公共翻译键用于格式化数值与常见文案避免每个 Widget 重复造轮子。下表完整整理自 docs/widgets/authoring/translations.md 的 Common Translations 一节。数值格式化键键示例输出说明common.bytes1,000 B按字节格式化数字common.bits1,000 bit按比特格式化数字common.bbytes1 KiB按二进制字节格式化common.bbits1 Kibit按二进制比特格式化common.byterate1,000 B/s格式化字节速率common.bibyterate1 KiB/s格式化二进制字节速率common.bitrate1,000 bit/s格式化比特速率common.bibitrate1 Kibit/s格式化二进制比特速率common.percent50%格式化百分比common.number1,000格式化数字common.ms1,000 ms格式化毫秒数common.date2024-01-01格式化日期common.relativeDate1 day ago格式化相对日期common.duration1 day, 1 hour格式化时长文本键键翻译说明resources.cpuCPUCPU 使用率resources.memMEM内存使用率resources.totalTotal总量resources.freeFree空闲量resources.usedUsed已用量resources.loadLoad负载值resources.tempTEMP温度值resources.maxMax最大值resources.uptimeUP运行时长这些键的英文值定义在 public/locales/en/common.json 的resources与common节点下是各语言common.json中对应翻译的基准。此外common节点还包含months/days/hours/minutes/seconds等时长单位键供duration格式化使用。数值与时间的语言感知格式化实现翻译键背后真正的格式化逻辑由 next-i18next 的自定义 formatter 完成全部实现在 next-i18next.config.js 中。该文件在应用启动时注册了六个格式化器bytes基于prettyBytes逻辑实现字节单位换算支持bits比特、binary1024 进制两个选项从而衍生出common.bytes/bits/bbytes/bbits四种形态rate计算单位时间速率输出如1,000 B/s、1 KiB/s支持bits、binary、decimals选项percent将 0–100 的数值除以 100 后按Intl.NumberFormat的百分比样式输出date通过Intl.DateTimeFormat按当前语言格式化日期relativeDate借助Intl.RelativeTimeFormat输出1 day ago这类相对时间内部按 60 秒、1 小时、1 天、1 周、1 月、1 年的梯度自动选择单位duration将秒数拆分为月/天/小时/分钟/秒并拼接common.months等翻译单位输出如1 day, 1 hour。以英文common.json中的定义为对照public/locales/en/common.json例如bytes: {{value, bytes}}就是把数值交给bytesformatter 处理翻译者在其他语言中通常只需保留{{value, bytes}}占位符格式化便会自动使用该语言的数字与单位习惯。这正是所有数值内容都应本地化这一要求在实现层面的落地——翻译键只负责文案格式化器负责让数字也说当地语言。总结围绕 docs/more/translations.md 所述的协作流程可以把 Homepage 的多语言体系归纳为一条完整链路开发侧组件与 Widget 一律使用英文 翻译键useTranslation/Block label英文条目登记到 public/locales/en/common.json协作侧翻译者通过 Crowdin 平台为各语言贡献或改进翻译新语言通过 Crowdin Discussion 申请同步侧crowdin.yml 负责把en源文件分发到 public/locales/ 下的 45 个语言目录运行时侧serverSideTranslations在服务端加载语言字典i18n.changeLanguage支持动态切换zh-CN自动映射到zh-Hans加载失败回退英语next-i18next.config.js 中的自定义格式化器保证数字、日期、速率与时长都能按当前语言正确呈现。无论你是想把自己的首页切换成母语界面还是希望回馈社区让更多人用上母语版 Homepage都可以按本文的路径直接上手。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
