多语言支持

添加多语言支持以触达全球受众。

概述

多语言系统提供：

• 多种语言 - 支持任意数量的语言
• URL 前缀 - /en/posts、/zh-CN/posts
• 语言独立配置 - 不同的菜单、标题等
• 语言切换器 - 内置 UI 组件
• SEO - 正确的 hreflang 标签

基本设置

1. 配置语言

在 astro.config.mjs 中：

import { astroBlog, defineI18nConfig } from '@jet-w/astro-blog';
import { enConfig } from './src/config/locales/en';
import { zhCNConfig } from './src/config/locales/zh-CN';

const i18nConfig = defineI18nConfig({
  defaultLocale: 'en',
  locales: [
    { code: 'en', name: 'English', htmlLang: 'en', dateLocale: 'en-US' },
    { code: 'zh-CN', name: '中文', htmlLang: 'zh-CN', dateLocale: 'zh-CN' },
  ],
  routing: {
    prefixDefaultLocale: false,
  },
  localeConfigs: {
    'en': enConfig,
    'zh-CN': zhCNConfig,
  },
});

export default defineConfig({
  integrations: [astroBlog({ i18n: i18nConfig })],
});

2. 创建语言配置

为每种语言创建文件夹：

src/config/locales/
├── en/
│   ├── index.ts
│   ├── site.ts
│   ├── menu.ts
│   ├── footer.ts
│   ├── sidebar.ts
│   └── ui.ts        # UI 翻译
└── zh-CN/
    ├── index.ts
    ├── site.ts
    ├── menu.ts
    ├── footer.ts
    ├── sidebar.ts
    └── ui.ts        # UI 翻译

3. 配置每种语言

英文 (en/index.ts):

import { site } from './site';
import { menu } from './menu';
import { footer } from './footer';
import { sidebar } from './sidebar';
import { ui } from './ui';

export const enConfig = {
  site,
  menu,
  footer,
  sidebar,
  ui,
};

英文站点 (en/site.ts):

export const site = {
  title: 'My Blog',
  description: 'A blog about technology',
};

英文菜单 (en/menu.ts):

export const menu = [
  { name: 'Home', href: '/', icon: 'home' },
  { name: 'Posts', href: '/posts', icon: 'posts' },
  { name: 'About', href: '/about', icon: 'about' },
];

URL 结构

当 prefixDefaultLocale: false 时：

语言	URL
英文（默认）	/posts
中文	/zh-CN/posts

当 prefixDefaultLocale: true 时：

语言	URL
英文	/en/posts
中文	/zh-CN/posts

内容组织

方式 1：分开文件夹

为每种语言创建单独的内容文件夹：

content/posts/
├── blog_docs_en/    # 英文文档
│   └── ...
└── blog_docs_zh/    # 中文文档
    └── ...

方式 2：相同内容

使用语言感知的 frontmatter：

---
title: Hello World
lang: en
---

语言切换器

当配置多种语言时，语言切换器会自动出现在头部。

它显示：

• 当前语言标志/名称
• 包含所有语言的下拉菜单
• 链接到其他语言的相同页面

语言配置选项

语言定义

{
  code: 'en',           // URL 前缀
  name: 'English',      // 显示名称
  htmlLang: 'en',       // HTML lang 属性
  dateLocale: 'en-US',  // 日期格式化
  direction: 'ltr',     // 文本方向（ltr/rtl）
}

语言独立配置

每种语言可以覆盖：

配置	用途
site	标题、描述、作者
menu	导航链接
footer	页脚链接和文本
sidebar	文档树分组
ui	UI 翻译字符串

UI 翻译

博客为英文和中文内置了 50+ 个 UI 字符串的翻译。你可以在语言的 ui.ts 文件中覆盖任何字符串。

创建 UI 翻译

英文 (en/ui.ts):

import type { UITranslations } from '@jet-w/astro-blog';

export const ui: Partial<UITranslations> = {
  // 在这里覆盖任何 UI 字符串
  browsePosts: 'Browse Posts',
  aboutMe: 'About Me',
  searchPlaceholder: 'Search articles...',
  readMore: 'Continue reading',
};

可用 UI 键

分类	键
导航	home, blog, about, search
文章	posts, postList, noPostsFound, readMore, readingTime, minuteRead
标签与分类	tags, categories, allTags, allCategories, taggedWith, inCategory
归档	archives, postsInArchive
侧边栏	recentPosts, popularTags, friendLinks, documentTree
页脚	quickLinks, contact
搜索	searchPlaceholder, searchResults, noResults, searching, searchArticles, searchTips 等
Hero	browsePosts, aboutMe
分页	previousPage, nextPage, page, of
文章	publishedOn, updatedOn, author, tableOfContents, relatedPosts, sharePost
其他	backToTop, copyCode, copied, expand, collapse, viewMode, sortBy, draft
幻灯片	slides, slidesList
RSS	rssFeed

添加新语言

1. 添加到 locales 数组：

locales: [
  { code: 'en', name: 'English', htmlLang: 'en', dateLocale: 'en-US' },
  { code: 'zh-CN', name: '中文', htmlLang: 'zh-CN', dateLocale: 'zh-CN' },
  { code: 'ja', name: '日本語', htmlLang: 'ja', dateLocale: 'ja-JP' },  // 新增
],

2. 创建配置文件夹：

src/config/locales/ja/
├── index.ts
├── site.ts
├── menu.ts
├── footer.ts
├── sidebar.ts
└── ui.ts          # UI 翻译

3. 创建带翻译的 ui.ts：

import type { UITranslations } from '@jet-w/astro-blog';

export const ui: Partial<UITranslations> = {
  // 导航
  home: 'ホーム',
  posts: '記事',
  tags: 'タグ',
  categories: 'カテゴリー',
  search: '検索',

  // Hero 区域
  browsePosts: '記事を見る',
  aboutMe: '私について',

  // 搜索
  searchPlaceholder: '記事を検索...',
  noResults: '結果が見つかりません',

  // 根据需要添加更多翻译...
};

4. 创建 index.ts：

import { site } from './site';
import { menu } from './menu';
import { footer } from './footer';
import { sidebar } from './sidebar';
import { ui } from './ui';

export const jaConfig = {
  site,
  menu,
  footer,
  sidebar,
  ui,
  contentPathPrefix: 'blog_docs_ja',
};

5. 添加到 astro.config.mjs 的 localeConfigs：

import { jaConfig } from './src/config/locales/ja';

localeConfigs: {
  'en': enConfig,
  'zh-CN': zhCNConfig,
  'ja': jaConfig,  // 新增
},

RTL 语言

对于从右到左的语言（阿拉伯语、希伯来语）：

{
  code: 'ar',
  name: 'العربية',
  htmlLang: 'ar',
  dateLocale: 'ar-SA',
  direction: 'rtl',  // 启用 RTL
}

最佳实践

---

恭喜！你已完成配置指南。

返回 文档首页 了解更多主题。