Internationalization (i18n)

Kiln supports multiple languages for all user-facing UI strings such as buttons, labels, and tooltips. Set a language code and every built-in string adapts automatically — from the search placeholder to the "Back to top" link and the copy-code button. No template editing required.

How it works

All translatable strings are defined in a single Labels struct with 21 fields, one for each UI string used across Kiln's default and simple themes. A languages registry maps language codes (e.g., "en", "it") to fully populated Labels instances.

At build time, Kiln calls Resolve(lang) with the language code you configured. If the code matches an entry in the registry, those labels are used; otherwise Kiln falls back to English automatically. This means a typo or unsupported code will never break your build — you simply get English strings.

The resolved labels are injected into HTML templates in two ways:

• Server-side — labels are rendered directly into the HTML during template execution (headings, tooltips, alt text, ARIA labels)
• Client-side — labels are passed to JavaScript via a hidden #kiln-labels element with data-* attributes, so client-side features like search and the copy-code button can read the correct strings at runtime

Configuration

Set the language with the --lang flag (short form -g) on the generate command:

kiln generate --lang it

Or set it permanently in your Configuration File:

lang: it

If neither is provided, Kiln defaults to en (English).

Supported languages

Translated strings

The table below lists every field in the Labels struct alongside its English default value.

Search

Navigation

Content metadata

UI actions & status

Adding a new language

New languages are added by editing the languages map in internal/i18n/i18n.go. There is no user-facing translation file — adding a language requires modifying Go source code.

Steps:

1. Open internal/i18n/i18n.go
2. Add a new entry to the languages map with your language code as the key (e.g., "fr" for French)
3. Fill in all 21 Labels fields with the translated strings
4. Run go test ./internal/i18n/... — the existing test suite verifies that every field is non-empty for all registered languages

"fr": {
    SearchPlaceholder: "Rechercher des notes...",
    ToggleTheme:       "Changer de thème",
    // ... all 21 fields
},

Limitations

• Only 2 languages built in — English and Italian are the only languages shipped with Kiln
• No user-facing translation file — adding a new language requires editing Go source code and rebuilding the binary
• All 21 strings must be provided — there is no per-field fallback to English; every field must be filled in for each language
• No right-to-left (RTL) layout support — languages that read right-to-left (Arabic, Hebrew, etc.) are not supported by the current templates
• Default and simple themes only — Custom Mode does not use the i18n labels; translations apply only to the built-in default and simple themes