多语言 (i18n)

当前支持的语言

项目默认支持两种语言：

语言代码	语言	URL 前缀
`en`	English	无（默认语言，隐藏前缀）
`zh-hans`	简体中文	`/zh-hans`

i18n 机制

项目采用基于 URL 前缀的国际化方案：

默认语言（en）隐藏 URL 前缀，例如 /blog、/docs
其他语言带语言前缀，例如 /zh-hans/blog、/zh-hans/docs
路由结构为 src/app/[locale]/，所有页面自动支持多语言

添加新语言

以添加日语（ja）为例，完整步骤如下：

第 1 步：注册语言

在 src/config/languages/registry/languages.json 中添加语言条目：

[
  { "code": "en", "label": "English", "native": "English" },
  { "code": "zh-hans", "label": "Chinese Simplified", "native": "简体中文" },
  { "code": "ja", "label": "Japanese", "native": "日本語" }
]

第 2 步：创建翻译文件

复制 src/locales/en.ts 为 src/locales/ja.ts，并翻译所有文本：

// src/locales/ja.ts
export const ja = {
  nav: {
    blog: "ブログ",
    docs: "ドキュメント",
    twitter: "Twitter",
    youtube: "YouTube",
    // ...
  },
  common: {
    search: "検索",
    home: "ホーム",
    // ...
  },
  // ...
};

第 3 步：注册翻译

在 src/locales/index.ts 中导入并注册新语言：

import { en } from "./en";
import { zhHans } from "./zh-hans";
import { ja } from "./ja";

export const locales = {
  en,
  "zh-hans": zhHans,
  ja,
};

第 4 步：创建内容目录

为新语言创建博客和文档的内容目录：

mkdir -p content/blog/ja
mkdir -p content/docs/ja

第 5 步：创建文档导航

创建 content/docs/ja/meta.json 定义日语文档的页面导航顺序：

{
  "title": "ドキュメント",
  "pages": [
    "index"
  ]
}

然后创建 content/docs/ja/index.mdx 作为文档首页。

翻译文件结构

翻译文件按功能模块分组，以下是 src/locales/en.ts 的基本结构：

export const en = {
  // 导航栏
  nav: {
    blog: "Blog",
    docs: "Docs",
    twitter: "Twitter",
    youtube: "YouTube",
    categories: "Categories",
    // ...
  },

  // 通用文案
  common: {
    search: "Search",
    home: "Home",
    readMore: "Read More",
    viewAll: "View All",
    noResults: "No results found",
    // ...
  },

  // Twitter 模块
  twitter: {
    title: "Twitter Accounts",
    followers: "{count} followers",
    // ...
  },

  // YouTube 模块
  youtube: {
    title: "YouTube Channels",
    subscribers: "{count} subscribers",
    // ...
  },

  // 页脚
  footer: {
    copyright: "All rights reserved.",
    // ...
  },
};

UI 翻译使用

在服务端组件或工具函数中，通过 getTranslations() 获取当前语言的翻译对象：

import { getTranslations } from "@/lib/i18n";

// 获取指定语言的翻译
const t = getTranslations(locale);

// 使用翻译文本
const title = t.nav.blog; // "Blog" 或 "博客"

对于包含变量的翻译文本，使用 interpolate() 函数处理变量替换：

import { interpolate } from "@/lib/i18n";

// 翻译模板: "共 {count} 个频道"
const text = interpolate(t.youtube.subscribers, { count: 1200 });
// 输出: "共 1200 个频道"

Admin 翻译

后台管理面板使用独立的翻译文件，与前台分离：

src/locales/admin/en.ts - 英文后台翻译
src/locales/admin/zh-hans.ts - 中文后台翻译

如果添加新语言，也需要创建对应的 src/locales/admin/ja.ts 文件。

内容目录结构

博客和文档内容按语言分目录组织：

content/
  blog/
    en/           # 英文博客文章
      hello.mdx
      guide.mdx
    zh-hans/      # 中文博客文章
      hello.mdx
      guide.mdx
  docs/
    en/           # 英文文档
      meta.json
      index.mdx
    zh-hans/      # 中文文档
      meta.json
      index.mdx

每种语言的内容相互独立，文件名建议保持一致以便对照管理。不同语言的文章数量可以不同。

语言切换器

页面右上角自动显示语言切换按钮，用户可在已配置的语言之间切换。切换时 URL 会自动更新为对应语言的路径。

语言切换器会读取 languages.json 中注册的语言列表，新增语言后无需额外配置即可出现在切换器中。