English
About this handbook

This handbook belongs to the Quartz plugin quartz-multilanguage. And it is built with it: the switcher at the top right comes from there.

This box, too, appears twice in the configuration — once per language.

Multilanguage

3 Min. Lesezeit

Quartz knows one language per site — one locale in the configuration, and that is that. quartz-multilanguage adds everything missing to publish the same notes from one vault in several languages: it detects each page’s language, finds the translations of one another, brings a switcher, writes hreflang and og:locale, redirects the start page and tells a visitor when their language exists.

What it does

Detect every page's language

By the language folder (en/…), by a suffix in the file name (note.en.md) or by a frontmatter field — in the order you set. → 2

Find the translations of one another

Through a shared key in the frontmatter, through Obsidian aliases (compatible with the Obsidian plugin “Multilingual”) or simply through the same path. → 3

A switcher

As text links, as a drop-down without JavaScript or as flags; labelled with the language code, the name, the native name or the title of the translation. It leads to the translation of this page. → 4

What search engines need to know

<html lang>, hreflang with x-default and og:locale are right on every page. → 5

Visitors land in their language

The start page redirects by the browser’s language and remembers a choice. Where a translation is missing there is a redirect or a notice “only available in German”, and dates appear in the page’s language. → 6, 7

One site for all languages, or one per language

The usual case is one build with every language. Anyone wanting an address of their own per language builds only the ones needed. → 8

This site is its own evidence

It exists in German and English, out of one vault, with this plugin. The switcher at the top right is its component; change the language and you land on the translation of this page — except on the tag pages, which have no counterpart. There it takes you to the other language’s start page, and says so in the tooltip.

The nine chapters

ChapterThe question it answers
1 – Getting startedWhat Quartz does alone, and what is added here
2 – DetectionHow does a page know which language it is in?
3 – LinkingHow do two versions of one page find each other?
4 – The switcherWhat the change looks like, and what it says
5 – Addresses and metadataWhat search engines learn about the multilingualism
6 – RedirectsWhere does / lead, and what happens when a translation is missing?
7 – Notices and links“This page is also available in …” — and links that change language
8 – BuildingOne site for all languages, or one per language?
9 – ReferenceEvery option, every limit

In one minute

npx quartz plugin add github:boxi-os/quartz-multilanguage

One entry configures everything at once — detection, linking, switcher:

plugins:
  - source: github:boxi-os/quartz-multilanguage
    enabled: true
    order: 65
    options:
      languages:
        - { code: de, native: Deutsch, locale: de-DE }
        - { code: en, native: English, locale: en-US }
      defaultLanguage: de
    layout:
      position: header
      group: toolbar

At length under [[en/1-getting-started/02-your-first-bilingual-site|1.2 – Your first bilingual site]].

Where else it is written

The short version is the repository README. The sister plugin quartz-layout-box puts markup into the layout and works well alongside this one; both belong to QuartzControl, though the app is not required.

9 Dateien in diesem Ordner.