pyssg is pre-1.0 and under active development - APIs, config, and themes may change.
i18n reference

2 min read

i18n reference

Technical reference for the internationalization machinery: the routing plugin, the t() template function, and the UI-string tables. For a task-oriented guide, see the i18n how-to.

The i18n plugin

i18n(default_locale: str, locales: Sequence[str]) -> I18nPlugin

Routes documents by their top-level content directory (content/<locale>/...). default_locale must be one of locales, otherwise a ConfigError is raised at configuration time.

The plugin adds three variables to every page's template context:

Variable Type Description
lang str The current page's locale ("" when the plugin is not loaded).
translations list The same page in its other locales - each a {lang, url, title} mapping. Only locales that actually have the page are listed, so a switcher never links to a missing translation.
languages list[str] Every configured locale, sorted.

The t() template function

t(key: str, **vars: object) -> str

Injected into every template by the render step, independently of the i18n plugin - a single-language site can use it too. Lookup proceeds in order and stops at the first hit:

  1. The current page's lang table.
  2. The default-locale table - the i18n plugin's default_locale, or en when the plugin is not loaded.
  3. The key string itself - so a missing translation is visible, never fatal.

**vars are interpolated with str.format:

{{ t("post.reading_time", minutes=reading_time) }}

If the template string is malformed or a referenced variable is missing, t() returns the raw string rather than raising, keeping a render robust against an incomplete table.

String tables (i18n/<lang>.toml)

One TOML file per locale, discovered from two directories:

Location Role
<layout>/i18n/<lang>.toml Theme defaults (the built-in themes ship these).
<site>/i18n/<lang>.toml Site overrides, merged per key over the theme's.
  • Flattening - nested tables become dotted keys: [nav] with home = "..." is addressed as nav.home.
  • Override - when both files define a key, the site's value wins; keys the site omits keep the theme's value.
  • Values - coerced to strings; use {name} placeholders for t() variables.
  • Discovery - locales are taken from the files present on disk, so they need not match the i18n plugin's locales.

Determinism

A digest of the string slices a page can read (its locale table plus the default) is folded into the render cache key. Editing a table re-renders exactly the pages it affects, and two builds of the same tree stay byte-identical.