Language¶

With the help of contributors, templates are localized into more than 60 languages, making it easy to create documentation sites in your preferred language.

Configuration¶

Site language¶

You can set the site language in your configuration file with:

[project.theme]
language = "en"

theme:
  language: en

HTML5 only allows to set a single language per document, which is why Zensical only supports setting a canonical language for the entire project.

The following languages are supported:

Site language selector¶

If your documentation is available in multiple languages, a language selector pointing to those languages can be added to the header. Alternate languages can be defined via configuration:

[project.extra]
alternate = [
    { name = "English", link = "/en/", lang = "en" },
    { name = "Deutsch", link = "/de/", lang = "de" }
]

extra:
  alternate:
    - name: English
      link: /en/ # (1)!
      lang: en
    - name: Deutsch
      link: /de/
      lang: de

The following properties are required for each alternate language:

alternate.name

This value of this property is used inside the language selector as the name of the language and must be set to a non-empty string.

alternate.link

This property must be set to an absolute link, which might also point to another domain or subdomain not necessarily generated with Zensical. If it includes a domain part, it's used as defined. Otherwise the domain part of the site_url as set in your configuration is prepended to the link.

alternate.lang

This property must contain an ISO 639-1 language code and is used for the hreflang attribute of the link, improving discoverability via search engines.

Directionality¶

While many languages are read ltr (left-to-right), Zensical also supports rtl (right-to-left) directionality which is deduced from the selected language, but can also be set with:

[project.theme]
direction = "ltr"

theme:
  direction: ltr

Click on a tile to change the directionality:

Customization¶

Custom translations¶

If you want to customize some of the translations for a language, just follow the guide on theme extension and create a new partial in the overrides folder. Then, import the translations of the language as a fallback and only adjust the ones you want to override:

<!-- Import translations for language and fallback -->
{% import "partials/languages/de.html" as language %}
{% import "partials/languages/en.html" as fallback %} <!-- (1)! -->

<!-- Define custom translations -->
{% macro override(key) %}{{ {
  "source.file.date.created": "Erstellt am", <!-- (2)! -->
  "source.file.date.updated": "Aktualisiert am"
}[key] }}{% endmacro %}

<!-- Re-export translations -->
{% macro t(key) %}{{
  override(key) or language.t(key) or fallback.t(key)
}}{% endmacro %}

[project.theme]
language = "custom"

theme:
  language: custom