Skip to Content
Vuesho

Internationalization

Serve your docs in several languages, each with its own pages, URLs and UI texts.

Define your languages with defineI18n(), and pass them to createSite() with the i18n option:

vuesho.config.ts
import { createSite } from "vuesho/config";
import { defineDocs } from "vuesho/content";
import { defineI18n } from "vuesho/i18n";

const docs = defineDocs();

const i18n = defineI18n({
  languages: ["en", "cn"],
  defaultLanguage: "en",
  hideLocale: "default-locale",
});

export default createSite(docs.toFumadocsSource(), { i18n });

Each language has its own pages, page tree, URLs and search index. The layouts show a language switch. The languages are in the types of the site, so this.localizePath("fr", "/") is a type error.

Translating Pages

A translated page sits next to the original, with the language before the extension:

content/
├── index.md
├── index.cn.md
└── guide/
    ├── meta.json
    ├── meta.cn.json
    ├── install.md
    └── install.cn.md

meta.cn.json translates the title of the folder and its order of pages. Files without a language, like install.md, are in the default language.

To use a folder per language instead, like cn/guide/install.md, set parser: "dir" in defineI18n(). The folder of a language is then the first one of the URL, before the baseDir of a source, so docs.toFumadocsSource({ baseDir: "docs" }) puts content/cn/guide.md at /cn/docs/guide.

Fallback Language

A page without a translation shows the page of the default language, at the URL of its own language: /cn/guide/english-only shows the English page. Set fallbackLanguage to another language to fall back to it, or to null for none: the page then doesn't exist in that language, and its URL is a 404.

A page shown in the fallback language is not a translation. Its canonical link is the URL of the page it shows, like /guide/english-only, and its page data has noindex: true: search engines, the sitemap, llms.txt and the alternate links of other pages leave it out.

URLs

The language is the first segment of the URL. hideLocale sets which languages have it:

  • "never", the default: every language has its prefix, like /en/guide/install and /cn/guide/install. A URL without a prefix, like /guide/install, redirects to the page in the default language on a server. A static host has the redirect of / only, which leads to the home of the default language: its /en, or its first page when it has none there.
  • "default-locale": the default language has no prefix, like /guide/install, while others have one, like /cn/guide/install. On a server, a URL with the prefix of the default language, like /en/guide/install, redirects to the URL without it.

Vuesho tells the languages apart by their prefix, so hideLocale: "always" is a type error of defineI18n(), and fails when the site starts.

A link in a page leads to the URL as it is written: the language of the page isn't added to it. In a translated page, write the prefix of its language:

content/guide/index.cn.md
[安装](/cn/guide/install)

UI Texts

ui.translations translates the texts of the UI. i18n.translations() creates the translations of your languages, .extend(uiTranslations()) adds the keys of the UI, and .add() gives the texts by language. A key is the English text followed by its note in parentheses, which tells apart uses of the same text:

vuesho.config.ts
import { uiTranslations } from "vuesho/i18n";

export default createSite(docs.toFumadocsSource(), { i18n }).config({
  ui: {
    translations: i18n
      .translations()
      .extend(uiTranslations())
      .add({
        cn: {
          "Search(search trigger)": "搜索",
          "Search(search dialog)": "搜索",
          "On this page(table of contents)": "本页内容",
          "Edit on GitHub(edit page)": "在 GitHub 上编辑",
        },
      }),
  },
});

The keys and the languages are typed: a key that isn't in the list, or a language that the site doesn't have, is a type error. The full list of keys is in node_modules/vuesho/ui/.translations/keys.json.

A site without languages translates its UI with defineTranslations(), whose .add() takes the texts directly:

vuesho.config.ts
import { defineTranslations, uiTranslations } from "vuesho/i18n";

export default createSite(docs.toFumadocsSource()).config({
  ui: {
    translations: defineTranslations()
      .extend(uiTranslations())
      .add({ "On this page(table of contents)": "Contents" }),
  },
});

Language Names and Tags

site.languages holds what differs by language, by the key of the language:

  • label: the name of the language in the language switch, like "中文". It defaults to the key.
  • lang: the language tag, where the key isn't one, like "zh-CN" for cn. It is the <html lang> of the pages of the language and their hreflang, and it sets the direction of the text. It defaults to the key.
  • name and description: the name and description of the site in the language, in place of site.name and site.description.
  • link: where the language switch leads for the language, like the start page of its docs or a domain of its own. Without it, the switch leads to the page the reader is on, in that language.
vuesho.config.ts
export default createSite(docs.toFumadocsSource(), { i18n }).config({
  site: {
    name: "Acme Docs",
    languages: {
      en: { label: "English" },
      cn: { label: "中文", lang: "zh-CN", name: "Acme 文档" },
    },
  },
});

A key that isn't a language of the site is a type error. A language whose tag isn't valid, like zh_CN, fails when the site starts. On a site without i18n, the tag is site.lang.

ui.layoutProps can be a function of the language, to translate the links of the navbar. this.localizePath() gives a path in a language, with its prefix:

vuesho.config.ts
export default createSite(docs.toFumadocsSource(), { i18n }).config({
  ui: {
    layoutProps({ lang }) {
      return {
        links: [
          { text: lang === "cn" ? "版本" : "Releases", url: this.localizePath(lang, "/releases") },
        ],
      };
    },
  },
});

Plugins and Custom Pages

The default plugins and your custom pages follow the languages of the site:

  • Search has an index per language, and the dialog searches the language of the page.
  • llms.txt and llms-full.txt exist per language: at the root of the site for the default language, and at the prefix of the others, like /cn/llms.txt.
  • The sitemap lists the translations of each page, and each page links to its translations with hreflang alternate links. The translations of a page are the pages of other languages at the same URL without the prefix, in any source.
  • A view and a custom page exist in every language, at its prefix, and receive the language as lang. Their pages link to each other with hreflang alternate links, and the sitemap lists them as translations. A custom page in one language, like a landing page you don't translate, sets lang: definePage({ lang: "en" }).
  • The not found page of a language is the page at its /404, like /cn/404, which renders at every URL of the language without a page.
  • A plugin with texts of its own lists their keys in translations, and ui.translations of your site translates them.

Text Direction

The language tag sets the direction of the text. <html dir> is rtl for a language written from right to left, like Arabic (ar) or Hebrew (he), and ltr for others. The components of the UI follow it.

Switching Languages

The app in the browser holds the data of one language, like its page tree. Picking another language in the language switch loads the same page in that language as a new document, and so does a link to a page of another language.