国际化

设置支持的语言 ​

site.config.ts
ts
import { defineSiteConfig } from 'valaxy'

export default defineSiteConfig({
  languages: ['zh-CN', 'en'],
})

在配置中使用国际化 ​

如果你想要为 siteConfig.title/siteConfig.description 添加国际化支持，可以在 siteConfig 中设定键值。

提示

$t 是 Valaxy 提供的一个虚拟函数，它会添加特定的前缀 $locale: 以标记此处的文本需要国际化处理。 随后，Valaxy 会在页面中自动替换为对应语言的文本。 因此，它在页面上仍然是支持响应式的。

例如：

site.config.ts
ts
import { $t, defineSiteConfig } from 'valaxy'

export default defineSiteConfig({
  title: $t('siteConfig.title'),
  description: $t('siteConfig.description'),
})

然后在 locales 目录下创建对应的语言文件。

locales/zh-CN.yml
yaml
siteConfig:
  title: 你好，世界
locales/en.yml
yaml
siteConfig:
  title: Hello World

单页 i18n ​

提示

Valaxy 提出了一种基于 CSS 面向博客的 i18n 解决方案。

你可以在同一个页面中快速编写中英文博客。

如果你想了解实现原理，可参考 i18n。

效果如下（点击按钮切换）：

另一种 i18n 方案。

更多内容：…

中文

书写方式如下：

md
另一种 i18n 方案。

更多内容：...


中文

标题 i18n ​

当然，Valaxy 同样支持标题的 i18n。原理同上。

你可以采用如下方式书写：

md
### 你好，世界

Frontmatter i18n ​

实现 title 和 description 的国际化：

md
---
title:
  en: Hello World
  zh-CN: 你好，世界
description:
  en: A simple i18n example
  zh-CN: 一个简单的 i18n 示例
---

分类/标签 i18n ​

Valaxy 会自动在 locale 文件中查找 tag.{tagName} / category.{categoryName} 对应的翻译。 如果找到，则显示翻译后的文本；如果没有找到，则原样显示。

你只需要在 frontmatter 中写 tag/category 的 key，无需添加任何特殊前缀：

posts/hello-world.md
md
---
categories:
  - test
tags:
  - notes
---

然后在 locales 目录中定义翻译：

locales/zh-CN.yml
yaml
category:
  test: 测试
tag:
  notes: 笔记
locales/en.yml
yaml
category:
  test: Test
tag:
  notes: Notes

提示

没有定义翻译的 tag/category 会原样显示。 例如 valaxy 这个 tag 如果没有在 locale 文件中定义 tag.valaxy，就会直接显示 valaxy。

旧版 `$locale:` 前缀方式（向后兼容）

旧版本需要在 frontmatter 中使用 $locale: 前缀：

md
---
tags:
  - $locale:tag.notes
categories:
  - $locale:category.test
---

该方式仍然兼容，但推荐使用上述更简洁的方式。

校验级别 ​

Valaxy 会在 valaxy dev / valaxy build 期间检查 taxonomy i18n。 你可以在 valaxy.config.ts 中通过三个级别控制它的行为：

  • off：跳过检查
  • warn：输出 warning 并继续流程
  • error：输出全部问题后，以错误结束
valaxy.config.ts
ts
import { defineValaxyConfig } from 'valaxy'

export default defineValaxyConfig({
  build: {
    taxonomyI18n: {
      level: 'warn',
    },
  },
})

贡献者