Internationalization: Details
Which language a page belongs to
The path decides the language: a page whose path starts with /<language folder>/ belongs to that language, and every other page belongs to the root language. In the source, the root language's pages sit in their own folder (docs/en-US/), and they are served without the folder name; see Writing pages: Details.
The config a page ends up with is the config.ts of its language folder layered over the shared config and the VitePress locale config; see Configuration: Details.
Choosing a language pack
- The packs to choose from are the six built-in ones (
zh,en,ja,ko,fr,ar) plus those inlanguages; one with the code of a built-in pack is laid over it. - Take the current language's
lang, lowercase it (with_turned into-), and look for a pack with exactly that code. - If there is none, compare the primary language:
zh-CNandzh-TWboth use Chinese,en-GBuses English, andfr-CAuses French. - If there is still none, use English.
- Fill the gaps: missing interface strings are English, a pack without
fontsuses the theme's fonts, and one withoutdiris left to right. - The
messages,fonts,dirandmarkdownwritten in the language config are laid over the pack.
When settings.title, settings.labels, toc.overline, footer.message and search.placeholder are not set, they also come from the interface strings of the language pack, so one shared config has sensible defaults in every language. Strings written in the shared config are inherited by every language; strings that differ by language belong in the language config.
Where language packs are used
- At build time,
akariContentgenerates a VitePress locale for each language.labeldefaults to the language's own name fromIntl.DisplayNames, with a capital first letter (such asFrançais);dirdefaults to the pack's direction;markdownis the pack's Markdown strings with the language config's laid over them; andheadholds the language's font tags. VitePress renders the code block copy button and container titles from the locale'smarkdown. - In the page, the theme resolves the interface strings and fonts of the current language: the
messagesandfontsofuseAkariConfig(). - Parts of a page marked with a
langattribute (such as the language names in the language dialog) use that language's font stack. These rules are generated from every pack that hasfonts; the stylesheets don't name any language.
Where switching language goes
- Move the current path into the target language:
/getting-started/installation.html→/zh-CN/getting-started/installation.html, and remove the prefix in the other direction. - If the target language's navigation has this path, open it. The navigation includes every page of a parallel page group.
- Otherwise, open the target language's home page:
/for the root language,/<language folder>/for the others.
Only the target language's navigation counts, so a page that is not in the navigation (for example, a page outside the structure) is never a switching target.
Language dialog
- The language button is a round outlined icon button (
m3e-icon-button variant="outlined"). It is not rendered when there is only one language. - The dialog uses the same container transform as the search panel: the button expands into a centered panel, the icon before the panel title is the button itself, and closing returns the panel the way it came.
- Each language takes two lines in the list: its
labelon the first, and below it its name in the current interface language, fromIntl.DisplayNames(in an English interface,zh-CNshows as "Chinese (China)"). The current language is highlighted with a check icon. As with search results, only the list's first item has rounded top corners and its last rounded bottom corners. - Clicking a language switches to it and closes the dialog, with SPA navigation. Clicking with
⌘,Ctrlor another modifier key held opens it in a new tab. - On open, focus is on the current language, and
Tabmoves between languages.Esc, clicking the scrim or the close button closes the dialog, and focus returns to the language button. - On narrow screens, the button is at the bottom of the navigation drawer, and the dialog covers the drawer.
Search scope
Each language has its own local index, and a search loads only the current language's, so results only ever come from the current language. HTTP and registered backends receive the current language's lang and locale and decide the scope themselves. The search panel's text and error messages follow the language.