配置多语言支持

配置多语言支持

概述

多语言文档能大幅扩展你的受众范围。Starlight 提供内置的 i18n 支持，采用基于语言的路由。本节介绍如何设置和管理多语言内容。

问答

Q：如何启用多语言支持？

A：在 astro.config.mjs 中添加语言配置：

export default defineConfig({
  integrations: [
    starlight({
      title: '我的文档',
      defaultLocale: 'root',
      locales: {
        root: { label: 'English', lang: 'en' },
        zh: { label: '中文', lang: 'zh-CN' },
        ja: { label: '日本語', lang: 'ja' },
      },
      sidebar: [
        {
          label: 'Getting Started',
          translations: { 'zh-CN': '快速开始', 'ja': 'はじめに' },
          items: [{ autogenerate: { directory: 'getting-started' } }],
        },
      ],
    }),
  ],
});

关键要点：

• root 是默认语言（服务在 /），其他语言使用带前缀的路径（/zh/、/ja/）
• label 在语言切换下拉菜单中显示
• lang 设置 HTML lang 属性，用于无障碍访问和 SEO
• 侧边栏项的 translations 提供本地化标签

Q：翻译后的内容放在哪里？

A：翻译内容放在语言前缀目录中：

src/content/docs/
├── index.md                        # 英文首页 (/)
├── getting-started/
│   └── installation.md            # 英文：/getting-started/installation/
└── zh/
    ├── index.md                    # 中文首页 (/zh/)
    └── getting-started/
        └── installation.md        # 中文：/zh/getting-started/installation/

Starlight 自动在语言切换器中将英文和中文版本关联起来。

Q：Starlight 如何处理 UI 翻译？

A：Starlight 的内置 UI 字符串（如”搜索”、“跳过内容”、“上一页”、“下一页”）会自动翻译为支持的語言。你也可以覆盖特定字符串：

starlight({
  locales: {
    root: { label: 'English', lang: 'en' },
    zh: { label: '中文', lang: 'zh-CN' },
  },
  // 需要时覆盖特定 UI 字符串
  customCss: ['./src/styles/custom.css'],
})

侧边栏标签使用上面展示的 translations 属性。

Q：如果某个页面还没有翻译怎么办？

A：Starlight 优雅地处理缺失翻译：

• 如果翻译后的页面不存在，语言切换器仍显示该语言但导航到回退（默认语言）页面
• 你可以在内容工作流中设置回退策略

推荐做法：使用内容迁移脚本（如本项目所用的）检测缺失翻译并生成占位页面：

## 英文版本正在编写中

This page is not available in English yet.

- 查看中文版：[/zh/getting-started/installation/](/zh/getting-started/installation/)

Q：如何管理跨语言的内容同步？

A：有三种常见策略：

策略	描述	适合
单一来源	用一种语言编写，通过脚本或服务翻译	小团队，明确的信息源
并行编辑	每种语言独立维护	有语言专员的大团队
混合	单一来源 + 重要页面手动覆盖	成长中的团队，质量关键内容

我们的做法：采用”单一来源”模式，以中文为信息源。迁移脚本（scripts/migrate-content.mjs）处理源目录、生成 frontmatter，并将内容同步到 Starlight 内容目录。英文版本或手动翻译，或显示占位页面。

Q：如何添加本地化的侧边栏标签？

A：在侧边栏分组上使用 translations 属性：

sidebar: [
  {
    label: 'Introduction',
    translations: {
      'zh-CN': '引言与预备知识',
      'ja': 'はじめに',
    },
    items: [{ autogenerate: { directory: 'introduction' } }],
  },
]

页面标题（来自 frontmatter）自动用于 autogenerate 生成的侧边栏项。

正在开发商业 IoT 产品？

我们提供 ESP32 ODM 定制设计与制造服务。从原型到量产——编写这套教程的团队，可以和你一起实现。

联系我们 →