fix(docs):調整文件建置的國際化語系格式以確保相容性 #233
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This reverts commit e3a6146.
BREAKING CHANGE: This commit adapts the documentation build process to a new version of `mkdocs-static-i18n` which enforces a new locale format. The `zh-TW` locale is no longer supported and has been replaced with `zh_TW`. This change includes: - Renaming all `zh-TW` files to `zh_TW`. - Updating all internal links to use the new `zh_TW` locale. - Updating the `mkdocs.yml` to use the new `zh_TW` locale.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Pull request type
Please check the type of change your PR introduces:
問題描述
文件建置流程因
mkdocs插件（特別是mkdocs-static-i18n和mkdocs-autorefs）的更新而失敗。最初遇到的問題包括：
mkdocs_autorefs: Multiple primary URLs found警告：已透過調整插件順序並在autorefs中新增resolve_closest: true解決。zh-TW語系檔案時，babel函式庫回報ValueError: expected only letters, got zh-tw。這是導致建置失敗的核心問題。問題根源
mkdocs-static-i18n插件在新版本（例如 1.3.0）中引入了重大變更，特別是在語系格式驗證方面。它現在嚴格要求語系代碼必須符合babel函式庫的規範，不允許在語系字串中使用連字號 (-)。這意味著zh-TW格式不再被接受，而zh_TW才是有效的格式。此變更也影響了插件產生輸出目錄的方式，若未明確處理，預設會從zh-TW轉為zh-Hant。解決方案
為了解決這些相容性問題，並確保文件能夠成功建置，同時保持一致的檔案結構，我們進行了以下修改：
mkdocs.yml設定更新：autorefs插件移至i18n之前，以確保在多語系設定中正確處理交叉引用。autorefs設定：為autorefs插件新增resolve_closest: true，以更優雅地處理多個主要 URL 的情況。i18n語系設定調整：將i18n插件的languages設定更新為新的列表字典格式，並明確將en設定為預設語系。mkdocs.yml中所有zh-Hant的設定明確改為zh_TW，以符合babel的要求並維持繁體中文語系。檔案與目錄重新命名：
zh-TW的部分（例如index.zh-TW.md），都已重新命名為zh_TW（例如index.zh_TW.md）。docs_dev/overrides/partials/languages/zh-TW.html檔案也已重新命名為zh_TW.html。內部連結更新：
*.zh-TW.md的內部連結，都已更新為指向*.zh_TW.md，以確保所有導航和交叉引用功能正常。影響 / 破壞性變更
此變更對繁體中文語系的路徑和檔案命名慣例引入了破壞性變更。
.../zh-TW/...或檔名.zh-TW.md.../zh_TW/...或檔名.zh_TW.md任何依賴舊
zh-TW路徑的外部連結或自動化流程，都需要更新為zh_TW。儘管如此，生成的文件在整體資料夾結構和內部連結方面，除了
zh-TW轉換為zh_TW之外，與舊版建置保持一致。這確保了所有文件連結在變更後仍然有效。驗證
文件現在可以在嚴格模式下成功建置，沒有任何錯誤。與舊版建置 (
site_old) 的比較結果也證實，結構上的差異僅限於zh-TW到zh_TW的語系轉換，而內容上的差異主要是由於主題/插件版本更新所致，這是可接受的。