全方位多语言 (i18n)#

什么是主语言？如何设置？#

主语言代表了你这个网站最核心、最默认的面向受众群体的语言。 你可以在 src/config.ts 中通过修改 siteConfig 轻松设置主语言，同时通过 languages 数组开启你想要支持的其它语言：

1
export const siteConfig: SiteConfig = {
2
    // ...
3
    lang: "zh_CN", // 将中文设为主语言
4
    languages: ["en", "ja", "ko"], // 声明支持的其它语言
5
    // ...
6
}

主语言与其他语言的区别#

1. 内容降级兜底：当你在其它语言环境中访问了未翻译的组件、未翻译的文章、或者未翻译的自定义 Tag 时，系统会默认退回到主语言抓取对应内容进行兜底展示（Fallback 策略）。
2. 路由前缀自动消隐：这是主语言系统的一大魔法！对于主语言来说，它的路由会自动去掉语言路径。
   • 比如你将主语言设置为 zh_CN，你在访问中文“关于”页面时，网址会干净利落地显示为：https://你的域名/about/。
   • 而当你切换到其它外语（如英语 en 或日语 ja）时，它们的网址则会规范地带上前缀：https://你的域名/en/about/ 或 https://你的域名/ja/about/。 这种设计既保持了主页面 URL 的优雅与简短，又对搜索引擎 (SEO) 极其友好。

主语言内容的专属文件夹（可选）#

在存放 Markdown 文件时，你可以直接将主语言的文章放在根目录（例如 src/content/blog/xxx.md）。但如果你是个强迫症，希望所有语言的文件都能隔离存放，系统同样支持为主语言创建独立的语言文件夹！

• 比如，在主语言为 zh_CN 的情况下，src/content/blog/zh_CN/xxx.md 与直接放在根目录的 src/content/blog/xxx.md 是完全等价的，它们最终都会被渲染到主语言的无前缀路由下。
• 注意防冲突：既然两者等价，请千万不要在根目录和 zh_CN 目录下同时创建两个同名（Slug 相同）的文章！如果发生这种路径冲突，系统为了防止内容覆盖，会在编译阶段直接报错。

1. 注册新的 I18n Key#

当你需要新增一个可以被翻译的词条时（例如在深层定制中加入了一个叫 tag.schoolmate 的新 Tag），你需要先在 src/i18n/i18nKey.ts 中注册它：

1
enum I18nKey {
2
    // ...
3
    tagSchoolmate = 'tag.schoolmate', // 注册新键值
4
}

WARNING

全站通用 Key 绝对不允许以中括号 [...] 开头（例如 [my-widget]title）。这是因为系统底层通过中括号来精确识别和隔离特定组件的专属翻译。如果你强行在全局 Key 中使用该格式，系统会在编译合并时主动报错拦截。若你对这种将特定组件的翻译“物理隔离”的机制感兴趣，请查阅更高级的 分块模块化 i18n 配置指南。

2. 在语言字典中补充翻译#

注册完毕后，进入 src/i18n/languages/ 目录，分别在对应的语言文件中补充翻译。 最重要的是：你必须在你的主语言文件（例如 zh_CN.ts）中补充它！

1
import I18nKey from "../i18nKey";
2
import type { Translation } from "../translation";
3

4
export const zh_CN: Translation = {
5
    // ...
6
    [I18nKey.tagSchoolmate]: "同学",
7
};

只要主语言配置了翻译，即便你忘记在 en.ts 或 ja.ts 中编写对应的翻译，系统也只会降级显示主语言的词条，绝不会造成页面崩溃。