国际化

学习如何在 TanStarter 模板中配置国际化、添加翻译文案和维护本地化内容

TanStarter 已内置基于 Paraglide JS 的国际化能力。默认语言是英文，中文通过 URL 前缀访问：

英文页面：/about
中文页面：/zh/about

涉及文件

国际化功能主要涉及以下文件：

settings.json

en.json

zh.json

middleware.ts

locale.ts

locale-switcher.tsx

文件	用途
`project.inlang/settings.json`	配置基础语言和支持的语言列表
`project.inlang/messages/en.json`	英文文案
`project.inlang/messages/zh.json`	中文文案
`src/lib/locale.ts`	导出语言配置、URL 工具和常用消息解析工具
`src/locale/middleware.ts`	接入 Paraglide 中间件，让服务端请求识别当前语言
`src/locale/paraglide/`	Paraglide 生成的运行时代码，不需要手动编辑
`src/components/layout/locale-switcher.tsx`	导航栏和菜单里的语言切换逻辑

不要手动修改 src/locale/paraglide/ 下的文件。它们由 Paraglide 根据 project.inlang/messages/*.json 自动生成。

添加 UI 文案

短文本、按钮、表单标签、错误提示、邮件标题等 UI 文案统一维护在 project.inlang/messages/*.json 中。

1. 添加消息 key

同时在英文和中文文件中添加同名 key：

project.inlang/messages/en.json

{
  "settings_profile_title": "Profile",
  "settings_profile_description": "Update your public profile information."
}

project.inlang/messages/zh.json

{
  "settings_profile_title": "个人资料",
  "settings_profile_description": "更新你的公开个人资料信息。"
}

建议使用模块前缀组织 key，例如：

auth_login_title
pricing_plan_pro_name
dashboard_empty_state_title
mail_verify_email_subject

这样后续排序、查找和维护会更清晰。

2. 在组件中使用文案

从 Paraglide 生成的 m 对象读取文案：

src/components/settings/profile-card.tsx

import { m } from '@/locale/paraglide/messages';

export function ProfileCard() {
  return (
    <section>
      <h2>{m.settings_profile_title()}</h2>
      <p>{m.settings_profile_description()}</p>
    </section>
  );
}

保存后，pnpm dev 会自动重新编译 Paraglide 运行时代码。新 key 生成后，就可以通过 m.your_key() 调用。

3. 排序并检查 key

添加或修改文案后，建议运行：

pnpm locale:sort
pnpm locale:check

pnpm locale:sort：按 key 前缀和名称排序所有语言 JSON
pnpm locale:check：检查不同语言文件里的 key 是否一致

如果某个 key 只添加到了 en.json，但忘记添加到 zh.json，检查命令会提示。

添加本地化 Markdown 内容

博客、更新日志、法律页面等长内容使用 Markdown 文件维护。英文使用基础文件名，中文在 .md 前添加 .zh。

content/blog/getting-started.md
content/blog/getting-started.zh.md

content/changelog/v1.0.0.md
content/changelog/v1.0.0.zh.md

content/pages/privacy.md
content/pages/privacy.zh.md

例如，为博客文章添加中文版本：

content/blog/my-first-post.md

---
title: My First Post
description: A short introduction to the product.
date: 2026-01-15
category: Tutorial
image: https://example.com/cover.jpg
---

English content...

content/blog/my-first-post.zh.md

---
title: 我的第一篇文章
description: 一篇简短的产品介绍。
date: 2026-01-15
category: 教程
image: https://example.com/cover.jpg
---

中文内容...

TanStarter 会把这两个文件识别为同一个 slug 的不同语言版本：

英文：/blog/my-first-post
中文：/zh/blog/my-first-post

文件名里的 .zh 只用于区分语言，不会出现在最终 URL 中。

添加新的语言

如果要新增语言，例如日语 ja，需要同时更新语言配置和文案文件。

1. 更新 Inlang 配置

在 project.inlang/settings.json 中添加新语言：

project.inlang/settings.json

{
  "baseLocale": "en",
  "locales": ["en", "zh", "ja"]
}

2. 添加消息文件

复制一份现有语言文件并翻译：

project.inlang/messages/ja.json

新文件需要包含和 en.json、zh.json 相同的 key。

3. 更新语言列表

在 src/lib/locale.ts 中为新语言添加名称、旗帜和 hreflang：

src/lib/locale.ts

export const localeConfig = {
  en: {
    flag: '🇺🇸',
    name: 'English',
    hreflang: 'en',
  },
  zh: {
    flag: '🇨🇳',
    name: '中文',
    hreflang: 'zh-CN',
  },
  ja: {
    flag: '🇯🇵',
    name: '日本語',
    hreflang: 'ja',
  },
} satisfies Record<Locale, LocaleConfig>;

语言切换器会读取 locales 和 localeConfig，自动显示新增语言。

4. 添加内容文件

如果博客、更新日志或法律页面也要支持新语言，按同样规则创建本地化 Markdown：

content/blog/getting-started.ja.md
content/changelog/v1.0.0.ja.md
content/pages/privacy.ja.md

如果你新增的语言不是 en 或 zh，还需要确认 content-collections.ts 里的语言后缀识别规则包含新语言。

常用命令

pnpm dev             # 启动开发服务器，并自动编译国际化运行时代码
pnpm build           # 构建生产版本，也会编译国际化运行时代码

pnpm locale:sort     # 排序消息 key
pnpm locale:check    # 检查不同语言的消息 key 是否一致
pnpm locale:compile  # 手动编译 Paraglide 运行时代码

日常开发中，通常只需要运行 pnpm dev。添加文案后再运行 pnpm locale:sort 和 pnpm locale:check，可以避免翻译 key 漏加。

下一步

页面

创建和维护页面

博客

添加本地化博客内容

网站配置

配置网站基础信息

元数据

配置 SEO 与页面元数据

TanStarter 已内置基于 Paraglide JS 的国际化能力。默认语言是英文，中文通过 URL 前缀访问：

英文页面：/about
中文页面：/zh/about

涉及文件

国际化功能主要涉及以下文件：

settings.json

en.json

zh.json

middleware.ts

locale.ts

locale-switcher.tsx

文件	用途
`project.inlang/settings.json`	配置基础语言和支持的语言列表
`project.inlang/messages/en.json`	英文文案
`project.inlang/messages/zh.json`	中文文案
`src/lib/locale.ts`	导出语言配置、URL 工具和常用消息解析工具
`src/locale/middleware.ts`	接入 Paraglide 中间件，让服务端请求识别当前语言
`src/locale/paraglide/`	Paraglide 生成的运行时代码，不需要手动编辑
`src/components/layout/locale-switcher.tsx`	导航栏和菜单里的语言切换逻辑

不要手动修改 src/locale/paraglide/ 下的文件。它们由 Paraglide 根据 project.inlang/messages/*.json 自动生成。

添加 UI 文案

短文本、按钮、表单标签、错误提示、邮件标题等 UI 文案统一维护在 project.inlang/messages/*.json 中。

1. 添加消息 key

同时在英文和中文文件中添加同名 key：

project.inlang/messages/en.json

{
  "settings_profile_title": "Profile",
  "settings_profile_description": "Update your public profile information."
}

project.inlang/messages/zh.json

{
  "settings_profile_title": "个人资料",
  "settings_profile_description": "更新你的公开个人资料信息。"
}

建议使用模块前缀组织 key，例如：

auth_login_title
pricing_plan_pro_name
dashboard_empty_state_title
mail_verify_email_subject

这样后续排序、查找和维护会更清晰。

2. 在组件中使用文案

从 Paraglide 生成的 m 对象读取文案：

src/components/settings/profile-card.tsx

import { m } from '@/locale/paraglide/messages';

export function ProfileCard() {
  return (
    <section>
      <h2>{m.settings_profile_title()}</h2>
      <p>{m.settings_profile_description()}</p>
    </section>
  );
}

保存后，pnpm dev 会自动重新编译 Paraglide 运行时代码。新 key 生成后，就可以通过 m.your_key() 调用。

3. 排序并检查 key

添加或修改文案后，建议运行：

pnpm locale:sort
pnpm locale:check

pnpm locale:sort：按 key 前缀和名称排序所有语言 JSON
pnpm locale:check：检查不同语言文件里的 key 是否一致

如果某个 key 只添加到了 en.json，但忘记添加到 zh.json，检查命令会提示。

添加本地化 Markdown 内容

博客、更新日志、法律页面等长内容使用 Markdown 文件维护。英文使用基础文件名，中文在 .md 前添加 .zh。

content/blog/getting-started.md
content/blog/getting-started.zh.md

content/changelog/v1.0.0.md
content/changelog/v1.0.0.zh.md

content/pages/privacy.md
content/pages/privacy.zh.md

例如，为博客文章添加中文版本：

content/blog/my-first-post.md

---
title: My First Post
description: A short introduction to the product.
date: 2026-01-15
category: Tutorial
image: https://example.com/cover.jpg
---

English content...

content/blog/my-first-post.zh.md

---
title: 我的第一篇文章
description: 一篇简短的产品介绍。
date: 2026-01-15
category: 教程
image: https://example.com/cover.jpg
---

中文内容...

TanStarter 会把这两个文件识别为同一个 slug 的不同语言版本：

英文：/blog/my-first-post
中文：/zh/blog/my-first-post

文件名里的 .zh 只用于区分语言，不会出现在最终 URL 中。

添加新的语言

如果要新增语言，例如日语 ja，需要同时更新语言配置和文案文件。

1. 更新 Inlang 配置

在 project.inlang/settings.json 中添加新语言：

project.inlang/settings.json

{
  "baseLocale": "en",
  "locales": ["en", "zh", "ja"]
}

2. 添加消息文件

复制一份现有语言文件并翻译：

project.inlang/messages/ja.json

新文件需要包含和 en.json、zh.json 相同的 key。

3. 更新语言列表

在 src/lib/locale.ts 中为新语言添加名称、旗帜和 hreflang：

src/lib/locale.ts

export const localeConfig = {
  en: {
    flag: '🇺🇸',
    name: 'English',
    hreflang: 'en',
  },
  zh: {
    flag: '🇨🇳',
    name: '中文',
    hreflang: 'zh-CN',
  },
  ja: {
    flag: '🇯🇵',
    name: '日本語',
    hreflang: 'ja',
  },
} satisfies Record<Locale, LocaleConfig>;

语言切换器会读取 locales 和 localeConfig，自动显示新增语言。

4. 添加内容文件

如果博客、更新日志或法律页面也要支持新语言，按同样规则创建本地化 Markdown：

content/blog/getting-started.ja.md
content/changelog/v1.0.0.ja.md
content/pages/privacy.ja.md

如果你新增的语言不是 en 或 zh，还需要确认 content-collections.ts 里的语言后缀识别规则包含新语言。

常用命令

pnpm dev             # 启动开发服务器，并自动编译国际化运行时代码
pnpm build           # 构建生产版本，也会编译国际化运行时代码

pnpm locale:sort     # 排序消息 key
pnpm locale:check    # 检查不同语言的消息 key 是否一致
pnpm locale:compile  # 手动编译 Paraglide 运行时代码

日常开发中，通常只需要运行 pnpm dev。添加文案后再运行 pnpm locale:sort 和 pnpm locale:check，可以避免翻译 key 漏加。

下一步

页面

创建和维护页面

博客

添加本地化博客内容

网站配置

配置网站基础信息

元数据

配置 SEO 与页面元数据

涉及文件

添加 UI 文案

1. 添加消息 key

2. 在组件中使用文案

3. 排序并检查 key

添加本地化 Markdown 内容

添加新的语言

1. 更新 Inlang 配置

2. 添加消息文件

3. 更新语言列表

4. 添加内容文件

常用命令

下一步

页面

博客

网站配置

元数据

目录

国际化

涉及文件

添加 UI 文案

1. 添加消息 key

2. 在组件中使用文案

3. 排序并检查 key

添加本地化 Markdown 内容

添加新的语言

1. 更新 Inlang 配置

2. 添加消息文件

3. 更新语言列表

4. 添加内容文件

常用命令

下一步

页面

博客

网站配置

元数据

目录