技术预览提交反馈
Livemark
Livemark静态站点生成器

翻译

更新于 2026年11月12日

languages 数组可以把一个项目变成多语言站点。第一种语言是默认语言，保留原有的 URL；其他每种语言都在其语言代码下提供，因此西班牙语版的 /guide/ 位于 /es/guide/。

基本用法

livemark.config.ts
import { defineConfig } from "livemark"

export default defineConfig({
  title: { en: "Acme Docs", es: "Documentación de Acme" },
  languages: [
    { code: "en", label: "English" },
    { code: "es", label: "Español" },
  ],
})

然后把翻译放在原文旁边，并在扩展名前加上语言代码：

  • docs
    • guide.md
    • guide.es.md
    • guide
      • install.md

guide.es.md 不需要 path：它沿用原文的 URL 并加上所属语言的前缀。guide.md 位于 /guide/（或 frontmatter path: /start/）时，它就位于 /es/guide/（或 /es/start/）。页面按去掉语言前缀后的 URL 配对，因此顶栏中的语言选择器可以在它们之间切换。

译文上的 frontmatter path 和其他地方一样是确切的 URL：要完整写出 path: /es/guia/。它必须以该语言的前缀开头；URL 与原文不同的译文不再与原文配对。

语言

字段类型默认值用途
codestring—URL 片段和文件后缀，小写（例如 es）。
labelstring—显示在语言选择器中的名称。
localestringcode用于 <html lang>、hreflang 和日期的 BCP 47 标签。
dir"ltr" | "rtl"取决于 locale文字方向；阿拉伯语、希伯来语、波斯语、乌尔都语等为 rtl。
flagstring取决于 locale选择器中旗帜对应的两字母国家代码（例如 br）。
messagesPartial<Messages>内置翻译对单个界面字符串的覆盖。

顶栏中的选择器会显示每种语言的旗帜。默认取自 locale 的地区（pt-BR → 巴西），否则取与该语言关联最紧密的国家（en → 英国）；设置 flag 可以选择其他旗帜。只会打包已声明语言的旗帜；country-flag-icons 中没有对应旗帜的代码不显示旗帜。

没有 languages 时，站点的行为与之前完全相同：只有一种语言，即位于 / 的英语。

标记文章的语言

文件的语言按以下顺序确定：

  1. frontmatter 中的 language: es，适合文件名需要保持自由的情况，例如 blog/hola.md；
  2. 指明某个已配置语言的 .<code>.md 后缀，例如 guide.es.md；
  3. 否则，使用默认语言。

不对应任何已配置语言的后缀会被视为文件名的一部分，因此 vite.config.md 仍然是一篇英语文章。

翻译配置中的文本

title、description 和 banner，栏目的 title、siteTitle 和 siteDescription，以及链接的 title，都既可以是字符串，也可以按语言代码分别给出值。缺少某种语言时，回退到默认语言的值。

sections: [
  { title: { en: "Guide", es: "Guía" }, prefix: "/" },
  { title: "Blog", prefix: "/blog/", type: "blog" },
]

文章栏目和博客栏目会为每种语言复制一份：西班牙语站点获得 /es/ 和 /es/blog/，各自拥有独立的侧边栏、标签和 RSS 订阅源。更新日志栏目同样会复制到 /es/changelog/：每个版本外围的页面是西班牙语的，而版本说明保持更新日志文件中的原文，并将英语页面标为规范页面，因此它们不会出现在 sitemap 中。栏目前缀不能以某种语言的代码开头，上例中的 /es/ 已保留给西班牙语。

未翻译的页面

某种语言的侧边栏仍会列出没有对应翻译的默认语言文章，并以默认语言的代码标注，链接到原始页面。语言前缀下不会复制任何内容，因此搜索引擎只会看到每个页面一次。

界面字符串

Livemark 自身的标签文字（“On this page”、“Search docs...”、“Edit on GitHub” 等）内置英语、德语、西班牙语、法语、日语、俄语和中文版本，并根据语言的 locale 选用。你可以按语言覆盖其中任意一项：

languages: [
  { code: "en", label: "English" },
  {
    code: "es",
    label: "Español",
    messages: { "toc.title": "En esta página", "search.placeholder": "Buscar…" },
  },
]

未知的键会导致配置检查失败，因此拼写错误不会悄无声息地保留英文文本。对于 Livemark 未内置的语言，请在 messages 中设置所有需要翻译的字符串。完整的键列表见 markdown/source/models/message.ts 中的 Messages schema。

你在 .livemark/ 下覆盖的组件可以通过 useMessages hook 读取相同的字符串：

import { useMessages } from "livemark/hooks/site"

export function Footer() {
  const t = useMessages()
  return <p>{t("page.updated", { date: "Mar 7, 2025" })}</p>
}

每种语言获得的内容

  • 来自该语言的 <html lang> 和 dir，以及按其 locale 格式化的日期
  • 翻译之间的 hreflang 链接、指向默认语言的 x-default 链接，以及 og:locale
  • 仅限当前语言的搜索
  • 其前缀下独立的 llms.txt 和 Markdown 副本
  • 独立的博客 RSS 订阅源，以及预渲染并列入 sitemap 的首页

用 ❤ 和 Livemark 构建