語言與多語系

Zensical 的模板已經有超過 60 種語言的翻譯，可以輕鬆建立用你母語呈現介面的文件網站，例如搜尋框、目錄標題、按鈕提示等。

設定網站語言

[project.theme]
language = "zh-TW"

只能設定單一語言

HTML5 每份文件只允許一個語言，所以 Zensical 只支援替整個專案設定一個主要語言。

中文相關的語言代碼如下（都是 Complete，翻譯完整）：

語言	代碼
中文（台灣）	`zh-TW`
中文（繁體）	`zh-Hant`
中文（簡體）	`zh`
英文（預設）	`en`
日文	`ja`
韓文	`ko`

完整的語言清單與翻譯完成度，請見官方文件。

搜尋介面暫時只有英文

搜尋介面是全新實作，目前還沒有多語系。但搜尋語言仍然會依 theme.language 決定，見搜尋。

語言選擇器

如果同一份文件有多個語言版本，可以在頁首加上語言選擇器。每個語言需要三個屬性：

[[project.extra.alternate]]
name = "繁體中文"
link = "/zh/"
lang = "zh-TW"

[[project.extra.alternate]]
name = "English"
link = "/en/"
lang = "en"

屬性	說明
`name`	顯示在選擇器裡的語言名稱，不可為空字串
`link`	絕對連結，可以指向其他網域（不一定是 Zensical 建立的網站）。沒有網域的話，會自動加上 `site_url` 的網域
`lang`	ISO 639-1 語言代碼，用於連結的 `hreflang` 屬性，有助搜尋引擎辨識

文字方向

大多數語言是由左到右（ltr），Zensical 也支援由右到左（rtl）。預設會依語言自動判斷，也可以手動指定：

[project.theme]
direction = "ltr"

自訂翻譯

想修改某個語言裡的部分字串，先啟用 custom_dir（見網站客製化），在 overrides/partials/languages/ 建立新的檔案，例如 custom.html：

overrides/partials/languages/custom.html

<!-- 匯入目標語言與備用語言的翻譯 -->
{% import "partials/languages/zh-TW.html" as language %}
{% import "partials/languages/en.html" as fallback %}

<!-- 定義要覆寫的翻譯 -->
{% macro override(key) %}{{ {
  "source.file.date.created": "建立於",
  "source.file.date.updated": "更新於"
}[key] }}{% endmacro %}

<!-- 重新匯出 -->
{% macro t(key) %}{{
  override(key) or language.t(key) or fallback.t(key)
}}{% endmacro %}

然後把語言設成這個自訂檔案：

[project.theme]
language = "custom"

en 一定要當備用語言

en 是主題的預設語言，必須永遠當作最後的備用，否則沒有翻譯的字串會出錯。

總結

想做的事	設定
設定介面語言	`theme.language = "zh-TW"`
語言選擇器	`[[project.extra.alternate]]`
文字方向	`theme.direction`
覆寫部分翻譯	`overrides/partials/languages/custom.html`

參考資料

Language - Zensical