Starlight项目国际化(i18n)配置指南

前言

在当今全球化的互联网环境中，为网站提供多语言支持已成为基本需求。Starlight作为一款现代化的文档站点构建工具，提供了开箱即用的国际化(i18n)解决方案。本文将详细介绍如何在Starlight项目中配置多语言支持，包括基础配置、内容组织、UI翻译等核心功能。

基础配置

1. 语言环境设置

在Starlight中配置国际化支持，首先需要在项目的配置文件中定义支持的语言：

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: '我的文档',
      defaultLocale: 'zh-cn', // 设置中文为默认语言
      locales: {
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
        en: {
          label: 'English',
        },
        ja: {
          label: '日本語',
          lang: 'ja',
        },
      },
    }),
  ],
});

关键配置项说明：

• defaultLocale: 指定默认语言，当其他语言版本内容缺失时会回退到此语言
• locales: 定义支持的语言列表，每个语言需要指定：
  • label: 在语言选择器中显示的文本
  • lang: 可选，设置HTML的lang属性
  • dir: 可选，设置文本方向(如RTL语言)

2. 内容目录结构

配置完成后，需要按照以下结构组织内容文件：

src/
  content/
    docs/
      zh-cn/    # 简体中文文档
      en/       # 英文文档
      ja/       # 日文文档

根语言配置

对于希望将默认语言作为根路径(不加语言前缀)的项目，可以使用root配置：

locales: {
  root: {
    label: '简体中文',
    lang: 'zh-CN', // 必须为root语言指定lang属性
  },
  en: {
    label: 'English',
  },
}

此时内容目录结构应调整为：

src/
  content/
    docs/
      index.md      # 根语言(中文)首页
      en/
        index.md    # 英文首页

内容回退机制

Starlight提供了智能的内容回退机制：

1. 当访问/zh-cn/about但该文件不存在时
2. 系统会自动回退到默认语言的/en/about内容
3. 同时显示"此页面尚未翻译"的提示

这一机制允许开发者先完成主要语言的内容，再逐步翻译其他语言版本。

UI国际化

1. 翻译站点标题

可以为不同语言设置不同的站点标题：

title: {
  'zh-cn': '我的文档',
  en: 'My Docs',
  ja: '私のドキュメント',
}

2. 翻译UI文本

Starlight的界面元素(如侧边栏、搜索框等)也支持多语言：

1. 首先配置i18n数据集合：

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};

2. 为每种语言创建翻译文件：

src/
  content/
    i18n/
      zh-CN.json
      en.json
      ja.json

3. 在JSON文件中添加翻译：

// zh-CN.json
{
  "search.label": "搜索",
  "404.text": "页面未找到",
  "expressiveCode.copyButtonTooltip": "复制到剪贴板"
}

3. 自定义翻译字段

可以扩展默认的翻译schema添加自定义字段：

schema: i18nSchema({
  extend: z.object({
    'custom.label': z.string().optional(),
  }),
}),

在组件中使用翻译

基本用法

<p>{Astro.locals.t('search.label')}</p>

带变量的翻译

// zh-CN.json
{
  "welcome": "欢迎，{{user}}!"
}

<p>{Astro.locals.t('welcome', { user: '张三' })}</p>

获取当前语言信息

<p>当前语言方向: {Astro.locals.t.dir()}</p>
<p>当前语言代码: {Astro.currentLocale}</p>

最佳实践建议

1. 内容一致性：保持各语言版本的目录结构和文件名一致
2. 渐进式翻译：先完成主要语言内容，再逐步翻译其他语言
3. 文化适配：注意不同语言的排版差异，特别是RTL语言
4. 测试验证：部署前检查各语言版本的显示效果
5. 翻译管理：考虑使用专业翻译管理系统(TMS)管理多语言内容

结语

Starlight的国际化支持让开发者能够轻松构建多语言文档站点。通过合理的配置和内容组织，可以为全球用户提供本地化的浏览体验。本文介绍的功能涵盖了从基础配置到高级定制的各个方面，开发者可以根据项目需求灵活选择适合的方案。