多语言支持 (i18n)¶

为你的 Zensical 网站添加多语言支持

功能开发中

多语言支持 (Internationalization) 是 Zensical Roadmap 中的重要功能，目前正在积极开发中。以下内容基于官方规划和 Material for MkDocs 的实现，具体配置请以官方发布为准。

官方规划¶

根据 Zensical Roadmap，多语言支持将包含以下特性：

灵活的内容组织¶

Zensical 将支持多种组织多语言内容的方式：

后缀方式：index.md、index.zh.md、index.ja.md
文件夹方式：en/index.md、zh/index.md、ja/index.md

AI 驱动的翻译工作流¶

利用现代 LLM 提供高性价比的翻译
追踪文档变更，自动生成翻译草稿
简化多语言内容的维护

全面本地化¶

UI 元素本地化
代码示例本地化
跨语言一致的用户体验

灵活的部署模式¶

支持统一构建所有语言
支持按语言单独构建和部署

当前可用配置¶

界面语言设置¶

设置网站界面语言：

[project.theme]
language = "zh"  # 中文界面

支持的语言代码：

代码	语言
`zh`	简体中文
`zh-TW`	繁体中文
`en`	英语
`ja`	日语
`ko`	韩语
`de`	德语
`fr`	法语
`es`	西班牙语

搜索语言配置¶

配置搜索支持的语言：

[project.plugins.search]
lang = ["zh", "en"]  # 支持中文和英文搜索

临时解决方案¶

在官方多语言功能发布前，可以使用以下方案：

方案一：多仓库/多分支¶

为每种语言创建独立的仓库或分支：

my-docs/           # 主仓库（英文）
my-docs-zh/        # 中文仓库
my-docs-ja/        # 日文仓库

方案二：子目录结构¶

在同一项目中使用子目录：

docs/
├── en/
│   ├── index.md
│   └── guide.md
├── zh/
│   ├── index.md
│   └── guide.md
└── index.md       # 语言选择页

配置导航：

nav = [
    { "English" = [
        { "Home" = "en/index.md" },
        { "Guide" = "en/guide.md" },
    ]},
    { "中文" = [
        { "首页" = "zh/index.md" },
        { "指南" = "zh/guide.md" },
    ]},
]

方案三：语言切换器¶

添加自定义语言切换器：

在 docs/overrides/partials/header.html 中：

<div class="language-selector">
    <a href="/en/">English</a>
    <a href="/zh/">中文</a>
</div>

翻译最佳实践¶

文件命名规范¶

docs/
├── index.md           # 默认语言（英文）
├── index.zh.md        # 中文版本
├── index.ja.md        # 日文版本
└── guide/
    ├── setup.md
    ├── setup.zh.md
    └── setup.ja.md

保持同步¶

使用 Git 追踪翻译状态
在 front matter 中标记翻译版本
定期检查内容同步

---
title: 快速开始
translation_of: quick-start.md
translation_date: 2025-01-22
---

翻译工具推荐¶

DeepL - 高质量机器翻译
Crowdin - 协作翻译平台
Weblate - 开源翻译管理
Transifex - 本地化平台

常见问题¶

如何处理未翻译的内容？¶

建议方案：

显示原文并标注"待翻译"
自动回退到默认语言
隐藏未翻译的页面

如何保持翻译同步？¶

建议方案：

使用 Git 分支管理翻译
设置翻译审核流程
使用 CI 检查翻译完整性

SEO 如何处理多语言？¶

建议方案：

使用 hreflang 标签
为每种语言设置独立的 sitemap
使用语言子目录或子域名

参考资源¶

提示：多语言支持功能正在开发中，请关注 Zensical 官方文档获取最新进展！