Internationalizing Websites

网站国际化

为 Next.js 网站添加多语言支持的完整工作流，遵循 SEO 最佳实践。

何时使用此 Skill

• 为现有网站添加新的语言版本
• 为新网站设置 i18n（国际化）
• 配置多语言 SEO
• 用户提及：“添加语言”“翻译”“本地化”“hreflang”“多语言”

支持的语言

常见目标市场：

• 🇺🇸 英语（en）- 全球市场
• 🇯🇵 日语（ja）- 亚洲市场
• 🇨🇳 中文（zh）- 中国市场

还支持以下语言：

• 韩语（ko）、葡萄牙语（pt）、西班牙语（es）、法语（fr）、德语（de）
• 阿拉伯语（ar）、越南语（vi）、印地语（hi）、印度尼西亚语（id）、泰语（th）
• 繁体中文（zh-hk）、意大利语（it）、俄语（ru）

国际化工作流

复制此清单并跟踪进度：

i18n Progress:
- [ ] Step 1: Prepare base language files
- [ ] Step 2: Add new language files
- [ ] Step 3: Update configuration files
- [ ] Step 4: Add translations
- [ ] Step 5: Configure SEO elements
- [ ] Step 6: Validate and test

步骤 1：准备基础语言文件

确保英文（en.json）文件已作为模板准备就绪：

必需目录：

• i18n/messages/en.json - 主要翻译
• i18n/pages/landing/en.json - 落地页翻译

检查结构：

# Check if base files exist
ls i18n/messages/en.json
ls i18n/pages/landing/en.json

如果缺少这些文件，请创建文件并添加网站所需的完整翻译键。

步骤 2：添加新语言文件

运行语言添加脚本：

node scripts/i18n-add-languages.mjs

此脚本的作用：

• 将 en.json 复制到所有目标语言文件
• 使用新语言更新 i18n/locale.ts
• 使用语言映射更新 i18n/request.ts
• 使用新的语言网址更新 public/sitemap.xml

脚本配置（位于 i18n-add-languages.mjs 中）：

• languages 数组 - 要添加的语言列表
• languageNames 对象 - 语言显示名称
• targetDirs 数组 - 包含翻译文件的目录

详细步骤指南请参阅 WORKFLOW.md。

步骤 3：验证配置更新

检查 i18n/locale.ts：

export const locales = ["en", "ja", "zh", "ko", ...];

export const localeNames: any = {
  en: "English",
  ja: "日本語",
  zh: "中文",
  ko: "한국어",
  ...
};

检查 i18n/request.ts：

• 已配置语言代码映射
• 包含 zh-CN → zh、zh-HK → zh-hk 映射

检查 public/sitemap.xml：

• 已列出所有语言版本
• 每个网址都包含 hreflang 标签

步骤 4：添加翻译

选项 A：使用 AI 翻译（速度更快，但需要审核）：

# Add structured data and pricing translations
node scripts/i18n-add-schema.js

在脚本的 translations 对象中配置翻译。

选项 B：手动翻译（推荐，质量更高）：

编辑各语言文件并填写准确的翻译：

# Open language file
code i18n/messages/ja.json

翻译最佳实践：

• 尽可能请母语人士翻译
• 保留目标语言中的 SEO 关键词
• 根据当地文化调整内容，不要只做直译
• 保持格式一致（占位符、变量）

语言代码参考请参阅 reference/locale-codes.md。

步骤 5：配置 SEO 元素

hreflang 标签 - 由站点地图自动生成，但请进行验证：

完整指南请参阅 reference/hreflang-guide.md。

本地化 meta 标签 - 在各语言文件中进行翻译：

{
  "metadata": {
    "title": "Your Site Title",
    "description": "Your SEO description"
  }
}

网址结构 - 验证格式是否正确：

• 英语：https://example.com/ 或 https://example.com/en/
• 日语：https://example.com/ja/
• 中文：https://example.com/zh/

第 6 步：验证和测试

构建项目：

npm run build

重要：继续之前，请修复所有错误。

手动测试：

1. 语言切换器：

   • 访问每种语言的版本
   • 确认语言切换器显示所有语言
   • 点击每个语言链接，确认加载了正确的页面

2. 内容显示：

   • 检查每种语言的所有页面是否正确呈现
   • 确认没有未翻译的文本（检查非英文页面中是否有英文）
   • 测试特殊字符是否正确显示（日语、中文、阿拉伯语）

3. SEO 元素：

   • 检查 <html lang="..."> 属性是否与页面语言匹配
   • 确认存在 <link rel="alternate" hreflang="..."> 标签
   • 检查 meta 标签是否使用正确的语言

自动化验证：

# Check sitemap
curl https://your-site.com/sitemap.xml | grep hreflang

# Validate hreflang (use online tool)
# Google Search Console > Internationalization > hreflang

SEO 检查清单 - 参见 reference/seo-checklist.md。

如果验证失败：

• 仔细检查错误消息
• 检查配置文件中是否有拼写错误
• 确认语言代码正确
• 返回第 3 步并修复问题

只有在所有验证都通过后才能继续。

重要说明

语言代码标准

使用 ISO 639-1（两字母代码），可选区域变体：

• en - 英语
• ja - 日语
• zh - 简体中文
• zh-hk - 繁体中文（香港）
• pt - 葡萄牙语
• pt-br - 巴西葡萄牙语

完整列表请参见 reference/locale-codes.md。

SEO 影响

正确的 i18n 设置有助于改善 SEO，具体表现为：

• 面向使用其母语的用户
• 避免重复内容处罚
• 帮助搜索引擎提供正确的语言版本

应避免的常见 SEO 错误：

• ❌ 根据 IP 自动重定向（会阻止搜索引擎抓取所有版本）
• ❌ 缺少 hreflang 标签（会导致重复内容问题）
• ❌ 各语言版本的 URL 结构不一致
• ❌ meta 标签未翻译

翻译质量

AI 翻译与人工翻译：

• ✅ AI：速度快、成本低，适合生成初稿
• ⚠️ AI：可能会遗漏文化细微差异，需要审核
• ✅ 人工：质量更高，能进行文化适配
• ⚠️ 人工：速度较慢，成本较高

推荐做法：

1. 使用 AI 生成初步译文
2. 请母语人士审核并润色
3. 邀请目标市场的用户进行测试
4. 根据反馈反复改进

Next.js i18n 路由

系统使用 next-intl 进行路由：

• 根据 URL 自动检测语言区域
• 语言切换器组件
• 本地化导航

配置位于 i18n/locale.ts 和 i18n/request.ts。

国际化后的任务

添加语言后：

1. 将更新后的站点地图提交到 Google Search Console
2. 为每种语言/区域创建单独的 Search Console 资源
3. 在 Analytics 中监控国际自然流量
4. 如果不同语言的转化率存在差异，则对译文进行 A/B 测试
5. 为国际抓取错误设置提醒

脚本位置

所有 i18n 脚本都位于 scripts/ 目录中：

• i18n-add-languages.mjs - 添加新的语言文件
• i18n-add-schema.js - 添加结构化数据译文

参考资料

• WORKFLOW.md - 详细的逐步工作流
• reference/hreflang-guide.md - hreflang 实施指南
• reference/locale-codes.md - 语言代码参考
• reference/seo-checklist.md - 国际 SEO 检查清单

故障排除请参见 WORKFLOW.md 中的故障排除部分。