refactor: change to vitepress

[Pimeng]

No description provided.

[sjfhsjfh]

TODO:

• markdown markup compatibility check
• i18n design

[sjfhsjfh]

Hi @YuevUwU

Since you've been involved in l10n work and are familiar with the repo, I'd love to get your perspective on how the mdbook → VitePress migration might affect the localization workflow.

My understanding is that the current .po-based approach (with gettext) is more translator-friendly — proper tooling support (Poedit, Weblate), fuzzy tracking, translation memory, etc. VitePress's official i18n approach is basically "one full copy of markdown files per language," which feels like a step backward for translators.

Would you mind sharing your thoughts on:

1. How significant the difference would be from a translator's perspective?
2. Whether it's feasible to keep the gettext/.po workflow with VitePress (e.g., generating localized md files from .po at build time)?

Totally understand if you're busy — just want to hear from someone who actually does the l10n work before we commit to this. Thanks! 🙏

好奇怪，都看得懂中文却还是在用LLM写英文comment🥺

[YuevUwU]

Tip

如果需要表達「我突然發現還有一些東西還沒完成/不完整，請不要合併」，除了 Close PR 外，也可以 Convert to draft

好奇怪，都看得懂中文却还是在用LLM写英文comment🥺

好吧，我也懶得校對用語和機翻意思了XD

---

其實沒PO的缺點 sjfh 講得差不多了，這裡只是做個很冗長的釐清(失焦注意)，還是得看官方立場，以及貢獻者或官方是否願意實作了，不外乎就三種：

• 先保留舊 mdbook 方案，那兩個新指南先單獨拉出來 commit 進去 (注意保留 Author)
• 把這個 PR 審一審（誤上傳的 asciinema record?(下方留言已解释)、字體注意 SIL 許可要求，不然看看能不能直接 NPM 包）直接合併，要不要兼容 PO 之後再說
• 等這個 PR 的 PO 功能完善後合併

建議考慮這些問題以劃清你們想做到的目標：

• 我們為什麼要遷移到 VitePress ？
• 這為我們帶來了什麼優勢？看到了哪些 mdbook 劣勢？
• 未來有想做自定義嗎？
• 這類自定義有辦法直接透過更改 mdbook 主題解決嗎？與實作 VitePress 的 PO i18n 成本相比呢？
  ^{雖然確實人家都做了，不合好像也不太好意思，不過還是注重長期發展}

另外這點也應該加入Markdown相容性檢查：

• 之前的 example.com/#heading 還能不能用，能 # 到最低多少層，引入英文文檔後還要確認 # 後的命名格式是否一致，否則得改

Q2：遷移至 VitePress 後，保留原有的 GNU gettext (PO) 工作流程是否可行？

Details

這種幾乎不依賴內部實作的可行性應該很大。
但實際上可不可行得試試才知道，Rust 的 mdbook-xgettext、Python 的 Translate Toolkit 或 mdpo，甚至 Weblate 平臺也有出
生成出的 Markdown 不支援，那就改成 VitePress (含自訂 Markdown-it 擴展) 跟 <使用的庫/實作> 的交集
問題就只剩下翻譯後比較 VitePress 與 <使用的庫/實作> 檢查幾種常見情況了(sjfh也放TODO了)

• 目前的文檔是否能預期呈現？改成兩者交集的風格能否修復？
• <span style="color"> 或想用的內嵌 HTML Tag 能否使用 (這與為什麼換成 VitePress 的問題有關)
• 換行和轉義邏輯是否一致，比如 GitHub Comment 和 HackMD (可選)就不需要行尾SPACESPACEENTER或\ENTER，但 GitHub Gist 和 CommonMark 就要。
• 過時的翻譯是否可正確保留原文
• (可選) <code> 是否應該翻譯

然後就是寫 CI，最後把編輯方法、特性、本地建置方式，與之前不同的部分跟 NuanR_Mxi 和 HLMC 通知一下應該就完事了
總之！只要敢嘗試 + 時間投入就可行！
^{不要像我一樣常常放棄，什麼都做不到...}

Q1：對一個菜鳥翻譯編輯者，PO有多重要

Important

有些不是 PO 本身帶來的好處，而是需要接入翻譯平臺，請注意區隔

Details

疊甲：我僅曾經用過 Poedit (Phira Docs/PO)、Crowdin (AnkiDroid/XML)、VS Code (Phira/Fluent) 簡單進行翻譯小編輯與概覽界面。
但從未從零開始進行翻譯，此處僅描述我微薄經驗帶來的心得
部分資訊與概念僅為簡單查詢和探索得出，可能並非精確描述，建議閱讀各說明文件釐清
(註：以下「不使用 PO 文件」指的是 VitePress 內置多語言各自 Markdown 文件的方法，現存的翻譯格式肯定還很多)

忽略不重要的特性

• Plural：與應用程式不同，文檔翻譯不是動態生成的，不需要適應數值變化
• 搜尋複雜性： 文檔通常不需要找原始碼或構建看看翻譯字串到底用在哪

若不使用 PO 文件，對於專案維護者？

• 過期翻譯未同步：比如資源包標準文檔中文都改成 ogg 了，未同步的英文還在 mp3
  沒有了PO，會更仰賴手動同步，下一次 Release 有改 Respack 相容多個又要在英文同步一次
  特別是 phira-doc 沒有固定活躍翻譯者 (TeamFlos/phira-docs#36)

若不使用 PO 文件，翻譯者翻譯時會感到怎樣？

在使用文字編輯器新建該語言的 Markdown 文件會出現的問題，我們以 Phira - Fluent - VS Code 為例

• 新增/刪除/更新翻譯：新增/刪除字段可以從行數或比較大致結構辨別，但仰賴翻譯者自己確實保留這些結構)。
  但這些操作更可靠的話需要我從 Git 找到上次翻譯的地方，然後將該位置的原文資料夾與最新 commit 進行比較
  每次都自律地這麼做才夠可靠，不然難道一句句重翻看到爛掉？
  (以前 Vibe 的自動化腳本還不知道可不可靠)
  • 解決方案：PO文件透過 msgupdate 自動上的 fuzzy flag 提示翻譯者重新審核
• 翻譯文字對齊：我會分割2個視口(原文文件|目標翻譯文件)，以理解上下文意思
  然後還要頻繁上下捲動看附近的字段，要知道英文內文通常比中文要長
  翻譯者也可能自行換行以符合當地人閱讀習慣，導致行號不可靠
  看完之後，肉眼比對或慢慢對齊key或根據行號
  唯一最接近自動對齊的就是 VS Code 的 File/Git Diff 了，但要看 Git 是否正確判別段落 (畢竟中間拉會一起滾)
  • 解決方案：POEdit、翻譯平臺等圖形界面就像表格那樣
    但還沒試過表格的表現，對於長橫向表格，可能會變成縱向字串列表
    這會比直接改整個 Raw Markdown 還要不直觀 (至少還可以拿去 Markdown Table Generator)
    更好的實現是像寫網頁那樣的 Live Update/Build

嗯，是的，如果不在意翻譯與原文一致性的話，獨立 .md 的一大好處就是實時預覽，編輯結構幾乎對應到輸出結構

共同功能

• Nearby String: [編輯器]查看翻譯檔案本身、[Crowdin]把 Sort 改成 Show All 時(非預設)的左側 String List、[Weblate]沒個翻譯字串界面的下方 (疑似固定數量的，能同網頁預覽整個檔案就完美了)

各本地化格式/平臺提供的功能

PO (GNU gettext)

• Comment: 開發者能提供上下文情境、類別或翻譯指引，多個翻譯檔案分類與標識符也能達到類似效果。另外還有給譯者手動寫得註釋。
  • 比如：「這是Dialog Box標題大字，請儘可能地縮短句子以免出界導致截斷」(TeamFlos/phira#313)、「這個訊息會在使用者點擊註冊後校驗時從右上方彈出」

Crowdin/Weblate

• Screenshot / Visual Context: 上傳圖片直觀展示畫面
  (對於整個項目的翻譯風格指南，請額外寫個指南)
• 協作一致性：使用者無需直接修改文件，全部仰賴同一個翻譯平臺，不仰賴使用者的編輯器、文字編碼、路徑格式環境，這可以避免連 .gitattribute 都幫不上忙的 UTF-8 BOM 剔除 TeamFlos/phira#614
• 社區投票、審核(且能專注於單一翻譯字串的)
• 翻譯記憶庫：相似字串、機器翻譯、其他語言翻譯參考，甚至能跨專案共享
• 術語表：(暫時還沒搞懂翻譯時怎麽用，目前 我創的 實際是拿來直接 search & replace 的，若沒附解釋或情境可能會更像是[相似字串]功能就能做到的東西)
  一種專注於翻譯/術語一致性的約束列表，包括但不限於
  • 對專有名詞或對該領域概念具有特殊意思/簡寫，而需要解釋或使用情境描述，及翻譯限制
  • 標記不應/不建議翻譯的術語
    • Minecraft 官方就對使用拉丁字母的語言限制某些詞彙不得翻譯，比如：Creeper、Nether、End，見 Official Glossary
  • 目標是讓App使用者理解這兩個東西/類型其實是一樣的
    • 比如：對該軟體 Role 要叫「身分組」還是「角色」在 UI 各處要一致
      在只有單一翻譯者，且開發者/管理者不介入維護的話，CSV/表格 和 GUI 其實沒差多少，
      主要場景是讓多個翻譯者或開發者/管理者能夠遵循一致的翻譯路線
    • 比如 Minecraft 中 zh-TW 約定將 Chiseled 統一譯為 「浮雕」，鼠標移到上面就看到固定對應譯文或概念意思了
    • Bricks 就有註明兩種解釋 "block of brick" 或 "A cuboid made of something."
      (這種多個解釋要從 Crowdin 右側的 Terminology 看才靠譜)
    • 我猜 MC 內部自己應該也有原文(en-US)規範表示什麼時候用 "Block of X" / "X Block"
      ^{不知道這些與幾個月前MC简中翻譯組的「砖」是否改名事件有關}

實作相關的分界(以目前的 mdbook 為例)

mdbook / mdbook-i18n-helper 功用

• 從 Markdown 提取應翻譯的字串與i18n註釋，生成 POT 文件
• 對於 沒有翻譯 或 含有 fuzzy flag 的翻譯字串使用原文

gettext 功用

• 在使用 msgupdate 時，會比對更新後原文與翻譯內容是否一致，若沒有，則激進地上 fuzzy flag。這代表這需要人工校對。[gt-3-2-workflow-flags]
• xgettext 本身能解析並提取部分語言的字串等生成 POT，但 markdown 仰賴第三方庫/自行實作
• PO 文件是從 POT 生成的
• gettext 的更多詳情請參考文檔：https://www.gnu.org/software/gettext/manual/html_node/index.html
• 關於 mdbook 與 i18n 功能的配合使用，見 comprehensive-rust 的翻譯指南
• 關於撰寫原文 Markdown 文件需要加註釋或其他功能的，見 mdbook-i18n-helper 的用例
• 也可參考同樣使用 PO 的專案，比如 Python Doc 翻譯

補充

使用者/PR審核員需要注意的：(不確定翻譯平臺有沒有防禦或正規化)

• 網頁安全：翻譯者是否使用任何惡意注入手段，包括不可見字元，使得 提早截斷 或 XSS 或 惡意破壞

[Pimeng]

@YuevUwU Thanks for the detailed questions. I’ll answer them here one by one.

I believe migrating to VitePress is the right move for our Game/API/Software documentation, especially for the additional features and future flexibility it brings.

Note

Parts of this comment may have been machine-translated from Chinese to English.

我們為什麼要遷移到 VitePress ？

Vitepress有很多新特性，比如完全可自定义的主题，活跃的社区还能为我们提供帮助
Vitepress offers a range of powerful features, such as fully customizable themes and support from an active community.

這為我們帶來了什麼優勢？看到了哪些 mdbook 劣勢？

相较于mdbook，Vitepress因其独特的样式，以及对于markdown的拓展，使其更为广泛用在API文档、产品说明书的场景
Compared to mdBook, Vitepress is widely used for API documentation and product manuals. It offers flexible theming and richer Markdown extensions, which fit our use case well. mdBook also supports theming and preprocessors, but VitePress’s ecosystem and Vue-based customization better match our long-term goals for a Game/API/Software documentation site.

未來有想做自定義嗎？

有，而且我的野心不止在自定义，我想要更好的主题便于人们去阅读文档，更沉浸式去理解其中的内容
Yes. My goal goes beyond simple customization — I want to design better themes that make documentation easier to read and provide a more focused, pleasant reading experience.

這類自定義有辦法直接透過更改 mdbook 主題解決嗎？與實作 VitePress 的 PO i18n 成本相比呢？

或许有，但是耗费的时间明显相对于 mdbook 要来的更多，Vitepress或许可以使用插件或代码的形式支持PO，但是相较于PO，我觉得直接翻一整页要来的更佳，因为在此基础上可以直接通读整篇文档来校对
We might be able to achieve similar results by heavily customizing mdBook’s theme, but that would likely take significantly more time than migrating to VitePress.
As for PO, it may be possible to support PO files in VitePress via plugins or custom code, but I think translating full pages/files directly works better for us — it lets translators review and proofread the entire document in context. That said, I’m happy to revisit this decision if there are strong reasons to stay with mdBook or to keep a PO-based workflow.

之前的 example.com/#heading 還能不能用，能 # 到最低多少層，引入英文文檔後還要確認 # 後的命名格式是否一致，否則得改

如果标题文字不变，VitePress 默认的锚点命名规则（ 详见此处教程 ）大概率会和 mdBook 类似（都是把标题转成 slug），但不能 100% 保证。因此我的计划是：

• 统一使用英文标题来保证中英文锚点一致；
• 或者使用自定义锚点（Markdown 后缀）来手动保持兼容；
• 或者在迁移后做一次旧链接检查。

VitePress automatically generates header anchors and supports configuring or customizing them via markdown.anchor (see the official docs for details ).

To address your specific questions:

• For old links like example.com/#heading: if the heading text stays the same, the auto-generated anchors will likely match the old ones, but we should verify this during migration.
• For consistency across languages: we can either use custom anchor suffixes in Markdown, or standardize on English headings, so that # fragments remain stable across translations.

Q2：遷移至 VitePress 後，保留原有的 GNU gettext (PO) 工作流程是否可行？

理论上，通过构建自定义插件或集成一些工具，是能够维持 GNU gettext（PO）工作流程的。但我尚未完全验证这一点，所以我会将其视为一项研究任务，并在有更具体计划后再向大家汇报
In theory, it should be possible to keep a GNU gettext (PO) workflow by building a custom plugin or integrating some tooling. I haven’t fully validated this yet, so I’ll treat it as a research task and report back with a more concrete plan.

Q1：對一個菜鳥翻譯編輯者，PO有多重要

PO 文件对译者来说非常有帮助，尤其是对于初学者而言：它们提供了结构化的背景信息，有助于保持术语的一致性，并且在源文本发生变化时便于更新译文。不过，就我们目前的工作流程而言，我们一直采用整页翻译加上多轮校对（包括借助人工智能辅助进行的检查）的方式，目前效果还不错。如果团队日后认为 PO 文件非常重要，我们也可以重新考虑这一点。
PO files can be very helpful for translators, especially beginners: they provide structured context, help keep terminology consistent, and make it easier to update translations when the source changes. That said, for our current workflow, we’ve been doing full-page translation plus multiple rounds of proofreading (including AI-assisted checks), and that has worked well so far. If the team finds PO essential later, we can revisit that.

網頁安全：翻譯者是否使用任何惡意注入手段，包括不可見字元，使得 提早截斷 或 XSS 或 惡意破壞

对于这一担忧，我认为每一次的PR都必须有至少2位作为代码审查并回复 LGTM ，同时 CI/安全扫描/构建 通过才能进行合并的操作；或者在构建前或显示前，可以添加一个处理环节，过滤或警告非常见的 Unicode 控制字符；对初次贡献者的 PR 必须进行更严格的审查
Regarding this concern, I believe every PR should require at least two reviewers for code review and approval (with LGTM ), and must pass CI/security scanning/build checks before being merged. Additionally, a pre‑processing step could be added before building or rendering to filter or warn about unusual Unicode control characters. PRs from first‑time contributors should undergo even stricter review.

[Pimeng]

除此之外，我和另一位在维护一个 非官方 的文档，你可以前往 https://phira-doc.star-trip.space/ 查看其效果，但是由于时间紧迫，我还没来得及制作i18n的工作，望谅解，目前是在反复调整文档的内容

还有一点忘记提的是：asciinema 并不是 误上传 的文件夹，我打算预留用于播放录制好的终端视频便于访客知晓构建Phira/Phira MP的过程