Internationalization

DataLeaf uses Hugo’s native i18n system for theme-owned interface strings.

The theme ships with:

i18n/
├── en.toml
└── pt-PT.toml

A site can override any key by providing its own files under i18n/, including region-specific files such as pt-PT.toml. The theme also mounts the Portuguese table as pt.toml, so bare pt works without duplicating the translation source or losing partial pt-PT overrides.

On its own, Hugo falls back only to the site’s defaultContentLanguage. It does not fall back from pt-BR to pt, or to English. Without a theme fallback, a site in French, German, or even en-GB would get empty labels, accessible names, and messages.

DataLeaf therefore adds English as the last fallback, one key at a time. Each string comes from the current language, then from the default content language, then from the theme’s English table. A partial site table therefore works: its keys are used and the rest stay in English. Hugo prints one warning per affected language:

WARN  DataLeaf: some interface text has no "fr" translation and uses English. …

To translate the interface into another language, copy the theme’s i18n/en.toml to i18n/<language key>.toml in your site, such as i18n/fr.toml, and translate the values. Keep the {{ .placeholders }} and __PLACEHOLDERS__ unchanged. If English is intended, silence the warning:

ignoreLogs = ["dataleaf-i18n-fallback"]

Builds run with --panicOnWarning fail on this warning until you add the translation table or the ignoreLogs entry.

Brazilian Portuguese is not shipped. The European Portuguese wording differs, for example “ligação” and “A carregar…”, so a pt-br site uses English until it adds i18n/pt-br.toml.

archive_date_format is a Go time layout rather than text. Write the reference date, Mon Jan 2 2006, in the order your language uses. For example, English uses Jan 2 and Portuguese uses 2 Jan; Hugo translates the month names.

Modern Hugo language configuration uses locale and label:

defaultContentLanguage = "en"

[languages]
  [languages.en]
    contentDir = "content"
    label = "English"
    locale = "en-US"
    weight = 1

  [languages.pt]
    contentDir = "content-pt"
    label = "Português"
    locale = "pt-PT"
    weight = 2

DataLeaf uses generated HTML output permalinks for theme navigation so language prefixes, output order, and subpath deployments are preserved. Translation links use absolute permalinks so sites with a different domain per language also work. An omitted label falls back to the language key; locale falls back through Hugo’s native language API.

Set direction = "rtl" on a right-to-left language. DataLeaf sets dir on the page and uses logical properties throughout, so the masthead, article rail, lists, rules, and pagination mirror, and pagination arrows point the way the page turns. Code blocks, inline code, and display mathematics keep reading left to right. The theme ships no right-to-left translation table; copy i18n/en.toml to your language’s key and translate it.

Shared parameters may be placed in the root [params] table and overridden in [languages.<key>.params]. Main sections, menus, and search remain scoped to the current language.

The translation tables cover:

• accessibility and navigation labels;
• reading time, entry counts, and pagination;
• discovery page kickers, such as the archive and documentation contents;
• article navigation and table of contents labels;
• light/dark/system theme labels;
• search UI, the header’s search link, and search status messages;
• heading permalink/copy feedback;
• technical shortcodes such as definition, theorem, remark, example, and proof;
• callout types (note, tip, warning, and important);
• table and equation accessibility labels, and taxonomy page counts;
• footer labels.

Site-owned content such as article titles, menu names, tags, categories, and prose remains the site’s responsibility. DataLeaf never translates it automatically. Give each language its own _index.md titles for sections and taxonomies, such as content-pt/tags/_index.md with title: "Etiquetas". Otherwise Hugo titles them from the directory or taxonomy name. Article labels and JSON-LD articleSection use the translated section title.

Two strings come from Hugo’s built-in templates rather than the theme: the RSS feed description (“Recent content in … on …”) and default taxonomy titles. Override Hugo’s rss.xml in your site, or add _index.md titles, if you need them translated.

• Each language has its own URLs, lists, archive, search page, and search index. Pages appear only in the languages they are written in.
• The language switcher appears on every page of a multilingual site. It links to the page’s translation when there is one, and otherwise to that language’s home page, so no language becomes unreachable. The current language is marked with aria-current="page", and every link carries lang and hreflang.
• Translated pages declare each other with <link rel="alternate" hreflang> and og:locale:alternate. Paginated pages omit the hreflang links, because their canonical URL has no translated counterpart.
• <html lang>, og:locale, JSON-LD inLanguage, canonical URLs, and og:url follow the current language, including under a subpath such as GitLab Pages’ /dataleaf/pt/.
• Dates use Hugo’s localized formats, such as “30 de setembro de 2026”, while datetime attributes and JSON-LD keep ISO dates.

DataLeaf’s JavaScript does not maintain separate translation dictionaries. Hugo renders localized strings into data-* attributes, and the scripts consume those values.

This keeps the source of truth in Hugo’s i18n tables and preserves the current language for:

• theme selection;
• search status messages;
• heading-link copy feedback.

During development, Hugo can report missing translation keys:

hugo --printI18nWarnings

The DataLeaf validation build enables this warning output and fails when a missing translation is detected. A regression test also checks that the English and Portuguese tables have the same keys, plural forms, and placeholders. It also checks that every key a template uses exists, and that templates look keys up through the English-fallback partial rather than calling T directly. An architecture fixture builds a French and German site to verify the fallback.