i18n

Set Supported Languages ​

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

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

Use i18n in Config ​

If you want to add i18n support for siteConfig.title/siteConfig.description, you can set key-value pairs in siteConfig.

TIP

$t is a virtual function provided by Valaxy. It adds a special prefix $locale: to mark that the text needs to be internationalized. Later, Valaxy will automatically replace it with the corresponding language text on the page. Therefore, it remains reactive on the page.

For example:

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

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

Then create corresponding language files in the locales directory.

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

i18n in One Page ​

TIP

Valaxy proposed a CSS-based i18n solution for blog.

You can quickly write English and Chinese blogs from the same page.

If you want to know how this works, see i18n.

The effect is as follows (click the button to switch).

Another i18n method.

More info…

English

Written like this:

md
Another i18n method.

More info...

English

Title i18n ​

Of course, Valaxy supports i18n on titles. Works the same as above.

You can write internationalized titles like this:

md
### Hello World

Frontmatter i18n ​

Internationalizing title and description:

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

Category/Tag i18n ​

Valaxy automatically looks up tag.{tagName} / category.{categoryName} translations in your locale files. If a translation is found, the translated text is displayed; otherwise, the raw key is shown as-is.

Simply write the tag/category key in your frontmatter — no special prefix needed:

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

Then define the translations in your locales directory:

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

TIP

Tags/categories without a corresponding translation are displayed as-is. For example, a tag named valaxy will simply render as valaxy if tag.valaxy is not defined in your locale files.

Legacy `$locale:` prefix (backward compatible)

Older versions required the $locale: prefix in frontmatter:

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

This still works for backward compatibility, but the simpler approach above is recommended.

Validation Level ​

Valaxy validates taxonomy i18n during valaxy dev / valaxy build. You can control the behavior with three levels in valaxy.config.ts:

  • off: skip validation
  • warn: print warnings and continue
  • error: print all issues, then exit with an error
valaxy.config.ts
ts
import { defineValaxyConfig } from 'valaxy'

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

Contributors