Theme translations

[clarfonthey]

Documentation issue

Summary

While it's clear that the translation system will be reworked eventually (#1058), right now a problem that exists is the fact that themes can't easily be translated. For example, if a theme includes custom translations that it wants to use via the trans template, these have to be included by the parent config.toml and can't be included directly as part of the theme.

Proposed solution

For now, probably the easiest method would be to simply copy the translations and languages.*.translations keys from theme.toml into the existing theme configs so that they can be combined with the config.toml keys.

[welpo]

if a theme includes custom translations that it wants to use via the trans template, these have to be included by the parent config.toml and can't be included directly as part of the theme

While this is true if you want to use the trans template, there are ways to translate a theme. See how the Zolarwind theme does it.

I implemented a more complex version of this for tabi: see the PR and the docs for end-users.

In short:

1. Load the data:

{# Load the internationalisation data for the current language from
the .toml files in the user's '/i18n' folder, falling back to the theme's.
This variable will hold all the text strings for the language #}
{%- set language_strings = load_data(path="i18n/" ~ lang ~ '.toml', required=false) -%}
{%- if not language_strings -%}
    {%- set language_strings = load_data(path="themes/tabi/i18n/" ~ lang ~ ".toml", required=false) -%}
{%- endif -%}

2. Set up a macro:

{% macro translate(key, language_strings="", default="") %}
{{- language_strings[key] | default(value=default) | safe -}}
{% endmacro %}

3. Translate:

{{- macros_translate::translate(key="visit_the_site", default="Visit website", language_strings=language_strings) -}}

[clarfonthey]

I mean, that's fair: you could do it manually, but it's still suboptimal that zola offers its own translation system and themes can't leverage that at all. Plus, eventually zola will have Fluent support, which will make it even more important to expose this to themes.

[Keats]

I don't really want to add more with the basic translation system since it's meant to be replaced. Although at the same time it seems fluent is going to be superseded by something else (MF2)?