Skip to content

为HMCL文档添加了en-us的支持 - #499

Open
I-am-shecatep wants to merge 2 commits into
HMCL-dev:mainfrom
I-am-shecatep:feat/i18n-en
Open

I-am-shecatep wants to merge 2 commits into
HMCL-dev:mainfrom
I-am-shecatep:feat/i18n-en

Conversation

@I-am-shecatep

Copy link
Copy Markdown

概要

本 PR 为文档站点补齐多语言支持:简体中文仍是默认语言、原有 URL 全部保持不变,在此基础上新增英文站点 /en/,为后续其他语言的翻译打好基础。

因为咪没什么时间,翻译是让Deepseek干的,我审了一遍没发现什么问题,如果有问题还请大佬指正喵!

实现方式

没有引入 jekyll-polyglot(其与 {% link %}、静态资源及仓库自定义插件存在兼容问题),而是新增了一个轻量的 Jekyll 插件 _plugins/i18n.rb:

  • 文件名即语言:foo.md 是默认语言(简体中文),foo_en.md 是英文翻译;英文文件不需要手写 permalink / lang / locale。
  • URL 自动继承:插件读取中文原文的 URL 并生成 /en 前缀,例如:
    • _launcher/isolation.md → /launcher/isolation.html
    • _launcher/isolation_en.md → /en/launcher/isolation.html
  • 链接自动改写:英文正文中的站内链接会自动指向对应英文页(仅当目标页面存在英文翻译时),翻译者保持与中文原文相同的链接即可。
  • 按语言切换站点信息:site.title、site.description、导航(_data/en/navigation.yml)以及 _data/en/ 下的数据文件(如 QQ 群列表 groups.csv)按当前页面语言生效。
  • 主题 UI 文案:Minimal Mistakes 4.28 的 include 已支持 locale 参数,英文页面的「Toggle menu / Updated / On this page」等 UI 文案自动为英文,中文页面保持原样。
  • 语言切换 + SEO:标题栏新增语言切换入口,页面 <head> 输出中英互指的 hreflang 标注。

为适配上述机制,新增/覆盖了少量主题文件(_includes/masthead.html、_includes/post_pagination.html、_layouts/collection.html),并移除了 locale 相关 include 的 include_cached 缓存。

变更内容

基础设施(commit 1:feat(i18n): add multilingual support with English site under /en/)

  • 新增 _plugins/i18n.rb
  • _config.yml:新增 i18n.default_locale / i18n.locales 配置
  • 新增 _data/i18n.yml、_data/en/navigation.yml、_data/en/groups.csv
  • 新增语言切换入口、hreflang 标注、同语言「上一页/下一页」隔离
  • 集合列表页按语言过滤,避免中英文章混排
  • index.json 只输出默认语言文章,保持 HMCL 客户端接口不变
  • 404 页双语;README 增加「多语言」贡献约定

英文翻译(commit 2:docs(i18n): add English translations for all documentation)

  • 46 篇 _en.md + settings_en.yaml,覆盖:首页、设置页、校验页、_docs、_launcher、_modpack、_multiplayer、_downloads、_pages、_eula 以及更新日志索引页
  • 中文首页与贡献指南补充英文站入口及翻译贡献说明

对现有功能的影响

  • 中文站点的 URL、页面结构与 index.json 输出均保持不变(index.json 与改动前逐字节一致),HMCL 客户端解析 /changelog/*.html 不受影响。
  • 构建/部署方式不变(仍为 bundle exec jekyll build),CI 与 PR 预览流程无需改动。

验证

  • 本地完整构建通过:开发环境、JEKYLL_ENV=production、以及带 baseurl(模拟 PR 预览)三种构建均成功;生成 47 个英文页面,中文页面数量不变。
  • 构建产物自动化检查:
    • 站内断链:0
    • 锚点失效:0
    • 翻译覆盖:0 缺失
    • 英文页面中文 UI 文案残留:0(语言切换按钮、ICP 备案号、更新日志正文等预期内容除外)
    • 语言隔离:中/英文章的列表页、翻页、导航互不串页
  • 本地预览:/(中文)、/en/(英文)

已知取舍

  • 更新日志(_changelogs/)目前只有中文内容,英文更新日志页展示中文条目并在页面中注明。
  • jekyll-feed 生成的 RSS 中中英文章会混合(插件本身不支持按语言过滤),后续可考虑拆分 feed。
  • _eula/hmcl_en.md 为非官方参考译文,页面中已注明以中文原版为准。
  • _docs/faq_en.md 中讨论「材质包/纹理包」中文译名的段落刻意保留了中文术语。

- 新增 _plugins/i18n.rb:识别 `<name>_<locale>` 翻译文件,自动为英文页面生成
  /en/ 路径,按页面切换站点标题/描述/导航,并改写正文中的站内链接
- _config.yml 增加 i18n.default_locale / i18n.locales 配置
- 新增 _data/i18n.yml、_data/en/navigation.yml、_data/en/groups.csv
- 新增语言切换入口(_includes/masthead.html)与 hreflang 标注
- 集合列表页、上一页/下一页按当前语言过滤,避免中英页面互相跳转
- index.json 仅输出默认语言文章,保持 HMCL 客户端接口不变
- 404 页双语;README 增加多语言贡献约定
- 新增 46 篇 `_en.md` 英文翻译及 settings_en.yaml,覆盖 _docs、_launcher、
  _modpack、_multiplayer、_downloads、_pages、_eula、_changelog 与首页
- 中文首页与贡献指南补充英文文档入口及翻译贡献说明
- 更新日志正文保持中文并在英文页面注明;EULA 为参考译文(以中文原版为准)
@zkitefly

Copy link
Copy Markdown
Member

@xcode review

@zkitefly

zkitefly commented Nov 1, 2026

Copy link
Copy Markdown
Member

File: _plugins/i18n.rb Lines: 85-126

这块多语言链接改写只处理了 HTML 的 href,没有覆盖 Markdown 里的站内链接。像 [xxx](/_docs/help.md)、[xxx](/_launcher/auto-installing.md) 这类常见写法,在英文页面里仍然会落到中文原始路径,而不是自动改写到 /en/...。这样会导致英文站点中的大量导航和帮助入口跳错语言,和这次“多语言支持”预期的行为不一致。

建议把 Markdown 链接和 HTML href 一并处理,或者在渲染后统一改写所有内部链接,而不是只匹配 href="..."。

由 copilot 审核

@zkitefly

zkitefly commented Nov 1, 2026

Copy link
Copy Markdown
Member

这个 pr 有演示页面吗

@I-am-shecatep

Copy link
Copy Markdown
Author

File: _plugins/i18n.rb Lines: 85-126

这块多语言链接改写只处理了 HTML 的 href,没有覆盖 Markdown 里的站内链接。像 [xxx](/_docs/help.md)、[xxx](/_launcher/auto-installing.md) 这类常见写法,在英文页面里仍然会落到中文原始路径,而不是自动改写到 /en/...。这样会导致英文站点中的大量导航和帮助入口跳错语言,和这次“多语言支持”预期的行为不一致。

建议把 Markdown 链接和 HTML href 一并处理,或者在渲染后统一改写所有内部链接,而不是只匹配 href="..."。

由 copilot 审核

抱歉喵没看出来问题诶,似乎是不会导致问题的
and以下是演示:

2026-11-03_20-03-07.mp4

@neveler

neveler commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

黄鱼不是重构成 11ty 了吗,rb 插件不能用了吧

@zkitefly zkitefly added the preview/create Create a preview for a specific pull request label Nov 4, 2026
@github-actions github-actions Bot removed the preview/create Create a preview for a specific pull request label Nov 4, 2026

@zkitefly zkitefly left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

只看了一些 到时候再看一下其他的

看了一下预构建版本 效果还不错 👍

Comment thread _eula/hmcl_en.md

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

我希望可以默认不弄英文 eula 🤔

Comment thread _data/en/groups.csv

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

希望可以直接映射中文文件夹的该文件,而不是再弄一个一模一样的

@zkitefly

zkitefly commented Nov 4, 2026

Copy link
Copy Markdown
Member

黄鱼不是重构成 11ty 了吗,rb 插件不能用了吧

能具体讲下吗,我怎么不知道(

@neveler

neveler commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

能具体讲下吗,我怎么不知道(

构建不运行旧 Ruby 插件。`theme/minimal-mistakes/prebuilt` 只保留首次迁移需要对齐的编译 CSS 和主题搜索脚本,不包含站点图片或字体副本。当前修改 SCSS 不会自动编译 CSS,需要另行接入样式编译。`theme/compat-code.json` 只保存未修改代码块的高亮 token,正文仍从 Markdown 构建,新代码会重新高亮。

黄鱼把项目重构成 11ty 了,这个东西是跑在 node 上面的,肯定不会跑 ruby 脚本。

预览构建能用是因为黄鱼重构的时候没有改 workflow 因此还是跑的 jekyll 。

@zkitefly

zkitefly commented Nov 4, 2026

Copy link
Copy Markdown
Member

能具体讲下吗,我怎么不知道(

构建不运行旧 Ruby 插件。`theme/minimal-mistakes/prebuilt` 只保留首次迁移需要对齐的编译 CSS 和主题搜索脚本,不包含站点图片或字体副本。当前修改 SCSS 不会自动编译 CSS,需要另行接入样式编译。`theme/compat-code.json` 只保存未修改代码块的高亮 token,正文仍从 Markdown 构建,新代码会重新高亮。

黄鱼把项目重构成 11ty 了,这个东西是跑在 node 上面的,肯定不会跑 ruby 脚本。

预览构建能用是因为黄鱼重构的时候没有改 workflow 因此还是跑的 jekyll 。

那需要更新 workflow 了

那么本 pr 需要更换非 ruby 脚本的方式了

@I-am-shecatep

Copy link
Copy Markdown
Author

能具体讲下吗,我怎么不知道(

构建不运行旧 Ruby 插件。`theme/minimal-mistakes/prebuilt` 只保留首次迁移需要对齐的编译 CSS 和主题搜索脚本,不包含站点图片或字体副本。当前修改 SCSS 不会自动编译 CSS,需要另行接入样式编译。`theme/compat-code.json` 只保存未修改代码块的高亮 token,正文仍从 Markdown 构建,新代码会重新高亮。

黄鱼把项目重构成 11ty 了,这个东西是跑在 node 上面的,肯定不会跑 ruby 脚本。

预览构建能用是因为黄鱼重构的时候没有改 workflow 因此还是跑的 jekyll 。

这下麻烦了,看来真得换了

@I-am-shecatep

Copy link
Copy Markdown
Author

能具体讲下吗,我怎么不知道(

构建不运行旧 Ruby 插件。`theme/minimal-mistakes/prebuilt` 只保留首次迁移需要对齐的编译 CSS 和主题搜索脚本,不包含站点图片或字体副本。当前修改 SCSS 不会自动编译 CSS,需要另行接入样式编译。`theme/compat-code.json` 只保存未修改代码块的高亮 token,正文仍从 Markdown 构建,新代码会重新高亮。

黄鱼把项目重构成 11ty 了,这个东西是跑在 node 上面的,肯定不会跑 ruby 脚本。
预览构建能用是因为黄鱼重构的时候没有改 workflow 因此还是跑的 jekyll 。

这下麻烦了,看来真得换了

11ty我不太熟啊

@neveler

neveler commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

那需要更新 workflow 了

那么本 pr 需要更换非 ruby 脚本的方式了

我在想,要不趁着这个时机直接换一个主题怎么样?现在是通过黄鱼手搓插件的方式支持的 minimal mistakes 主题,感觉不如直接换一个 11ty 的主题。

或者直接搓一个新主题?现在代码跑在 node 上调前端工具也比较方便。

This branch was successfully deployed

1 active deployment
github-pages — b3528b7e Deployed Nov 4, 2026 by zkitefly via preview-create-deploy #1004
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants