国际化系统

相关源文件

• docs/index.en.md
• mkdocs.yml

目的与范围

本文档描述了CS自学指南仓库中实现的国际化（i18n）系统。该系统使网站能够支持中文和英文内容，为全球用户提供双语体验。它涵盖了i18n插件的配置、跨语言内容组织以及生成特定语言版本网站的构建过程。

本页面主要关注多语言支持的技术实现。有关贡献翻译的信息，请参阅翻译工作流程。有关整体网站架构的详细信息，请参阅网站架构。

来源: mkdocs.yml61-117

系统架构

国际化系统基于MkDocs构建，并使用了专门的i18n插件。该插件处理网站导航的翻译、内容组织，并为每种支持的语言构建独立的网站版本。

国际化系统概述

来源: mkdocs.yml61-117

内容文件组织

来源: mkdocs.yml61-70 docs/index.en.md1-86

插件配置

国际化系统由MkDocs i18n插件提供支持，该插件在主mkdocs.yml文件中配置。该插件支持多种语言，并为每种语言提供可自定义的设置。

语言设置

系统目前支持两种语言

语言	本地化	默认	站点名称	构建
中文	zh	是	CS自学指南	是
英语	en	否	csdiy.wiki	是

配置指定中文（zh）为默认语言，这意味着没有语言后缀的内容被视为中文。对于英文内容，文件必须带有.en.md后缀。

来源: mkdocs.yml1-5 mkdocs.yml61-70

导航翻译系统

i18n插件包含了从中文到英文的导航项翻译的广泛映射。这使得网站能够保持一致的导航结构，同时显示适当的特定语言文本。

配置中定义的导航翻译的一部分

中文（原文）	英文（译文）
前言	Foreword
如何使用这本书	How To Use The Book
一个仅供参考的CS学习规划	指南
必学工具	Productivity Toolkit
计算机网络	计算机网络
数据库系统	数据库系统
编译原理	编译器

来源: mkdocs.yml71-117

内容组织

该仓库使用符合i18n插件期望的文件命名约定来组织多语言内容。

文件命名约定

内容文件遵循以下命名模式

• 中文（默认）：filename.md
• 英文：filename.en.md

例如，主索引页有两个版本

• 中文：index.md（隐式）
• 英文：docs/index.en.md

这种模式允许i18n插件自动关联跨语言的相应内容。

来源: docs/index.en.md1-86

目录结构保留

i18n系统在不同语言间保持相同的目录结构。当网站构建时，插件会创建特定语言的网站版本，同时保留原始目录层级。

来源: mkdocs.yml61-70

构建流程

国际化系统影响MkDocs构建网站的方式，为每种配置的语言创建独立的版本。

特定语言构建

在构建过程中，i18n插件会

1. 识别所有内容文件及其语言变体
2. 处理配置中的导航翻译
3. 为每种启用的语言构建独立的网站版本
4. 为所有页面创建特定语言的URL

构建输出包括一个完整的中文网站（在根路径）和一个完整的英文网站（在/en/子目录中）。

来源: mkdocs.yml61-70

搜索集成

国际化系统与搜索插件集成，以提供特定语言的搜索功能。搜索插件配置为支持中文和英文。

来源: mkdocs.yml118-121

用户体验

国际化系统为用户提供无缝的语言切换体验，同时保持他们在内容中的当前位置。

语言选择

用户可以使用网站界面中的语言选择器在不同语言之间切换。当用户更改语言时，他们将被重定向到所选语言的等效页面，同时保持他们在内容层级中的位置。

URL 结构

系统使用以下URL模式来区分不同语言版本

• 中文（默认）：https://csdiy.wiki/path/to/page
• 英文：https://csdiy.wiki/en/path/to/page

这种一致的URL结构有助于SEO，并便于在不同语言版本之间进行导航。

来源: mkdocs.yml2 mkdocs.yml61-70

总结

CS自学指南中的国际化系统通过以下方式高效管理多语言内容：

1. MkDocs中配置良好的i18n插件
2. 一致的文件命名约定
3. 全面的导航翻译
4. 特定语言的构建过程
5. 集成的搜索功能

这种实现使得该项目能够触及更广泛的受众，同时在不同语言间保持一致的结构和无缝的用户体验。

来源: mkdocs.yml1-5 mkdocs.yml61-117