🌐 feat(i18n): overhaul translation system & add languages

Revamp the existing translation system, simplifying management and adding several new languages. The new system reads from TOML files in the `/i18n` directory and improves template structures. It also enhances customisation options and robustness by providing fallbacks and modularity. - Implement a new, streamlined translation macro. - Load translations from `/i18n` TOML files. - Remove redundant configuration requirements. - Refactor templates to align with new i18n system. - Add support for Hindi, Japanese, Russian, Portuguese, Chinese, Italian, German, Ukranian, Korean, and French languages. - Credit Thomas Weitzel (@thomasweitzel) for inspiration.
welpo · Sep 12, 2023 · 5a49418 · 5a49418
1 parent 327545f
commit 5a49418
Show file tree

Hide file tree

Showing 46 changed files with 1,535 additions and 485 deletions.
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
@@ -262,40 +262,3 @@ if git diff --cached --name-only | grep -q "config.toml"; then
     # Add the generated subset.css file to the commit.
     git add static/custom_subset.css
 fi
-
-################################################################################
-# Update the README if the line numbers for the language section have changed. #
-################################################################################
-
-# File paths and names.
-config_file="config.toml"
-config_readme="README.md"
-
-# Ensure the required files are present.
-[ ! -f "$config_file" ] && error_exit "$config_file not found!"
-[ ! -f "$config_readme" ] && error_exit "$config_readme not found!"
-
-# Determine the line numbers for relevant sections in config.toml.
-lang_start_line=$(grep -n "^\[languages.es\]$" "$config_file" | cut -d: -f1)
-extra_start_line=$(grep -n "^\[extra\]$" "$config_file" | cut -d: -f1)
-lang_end_line=$((extra_start_line - 2))
-
-# Extract currently documented line numbers from README.
-documented_lines=$(grep -o 'https://github.com/welpo/tabi/blob/main/config.toml#L[0-9]*-L[0-9]*' "$config_readme" | grep -o 'L[0-9]*-L[0-9]*')
-doc_start_line=$(echo "$documented_lines" | cut -d'-' -f1 | tr -d 'L')
-doc_end_line=$(echo "$documented_lines" | cut -d'-' -f2 | tr -d 'L')
-
-# Ensure that the variables are set and are numbers.
-if [[ ! $lang_start_line =~ ^[0-9]+$ ]] || [[ ! $doc_start_line =~ ^[0-9]+$ ]] || [[ ! $lang_end_line =~ ^[0-9]+$ ]] || [[ ! $doc_end_line =~ ^[0-9]+$ ]]; then
-    error_exit "Line number variables are not set correctly."
-fi
-
-# Update the README if there's a discrepancy in the line numbers.
-if [ "$lang_start_line" -ne "$doc_start_line" ] || [ "$lang_end_line" -ne "$doc_end_line" ]; then
-    if ! perl -pi -e "s|https://github.com/welpo/tabi/blob/main/config.toml#L[0-9]*-L[0-9]*|https://github.com/welpo/tabi/blob/main/config.toml#L$lang_start_line-L$lang_end_line|g" "$config_readme"; then
-        error_exit "Perl processing failed for $config_readme"
-    fi
-
-    # Add updated README to commit.
-    git add "$config_readme"
-fi
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,7 +5,10 @@ Halló!
 Thanks for contributing to [tabi](https://github.com/welpo/tabi). Before implementing new features and changes, please [submit an issue](https://github.com/welpo/tabi/issues/new) so that we can discuss it.
 
 We welcome contributions in many forms, including:
+
 - Bug reports;
+- New translations;
+- Improvements to existing translations;
 - Feature requests;
 - Code patches;
 - Documentation improvements;

diff --git a/README.md b/README.md
@@ -14,7 +14,8 @@ tabi has a perfect score on Google's Lighthouse audit:
 
 ## Features
 
-- [X] Multi-language support.
+- [X] [Comprehensive multi-language support](https://welpo.github.io/tabi/blog/faq-languages/#how-does-tabi-handle-multilingual-support). Add as many languages as you wish.
+- [X] [Set any language as default](https://welpo.github.io/tabi/blog/faq-languages/#how-do-i-set-a-default-language-for-my-site). Set your base site to Chinese, Spanish, French, Hindi… or any [other supported language](/i18n). The theme's interface will be translated accordingly.
 - [X] Dark and light themes. Defaults to the OS setting, with a switcher in the navigation bar.
 - [X] Support for [comments using giscus, utterances, Hyvor Talk, or Isso](https://welpo.github.io/tabi/blog/comments/).
 - [X] Perfect Lighthouse score (Performance, Accessibility, Best Practices and SEO).
@@ -106,20 +107,22 @@ header = {title = "Hello! I'm tabi~", img = "img/main.webp" }
 
 The content outside the front matter will be rendered between the header title and the posts listing. In the screenshot above, it's the text that reads "tabi is a fast, lightweight, and modern Zola theme…".
 
-6. If you want a multilingual site, you will need to set up each language. In `config.toml`:
+6. If you want a multilingual site, you will need to set up each language. In `config.toml`, set the title and taxonomies for each language, like:
 
-- set the translations for a few strings;
-- set the title and taxonomies for each language;
-- add the `language_name.{code}` in `[extra]`. This is the text shown in the language switcher.
-
-See [these lines in the provided `config.toml`](https://github.com/welpo/tabi/blob/main/config.toml#L22-L134) for an example.
+```toml
+[languages.es]
+title = "~/tabi"
+taxonomies = [{name = "tags", feed = true}]
+```
 
 You will need an `_index.{language_code}.md` per language for each section (e.g. /blog or /projects) that you want to enable in that language.
 
 The same is true for individual posts, which should have the exact same name as the default language, with an extra `.{code}` before the extension (e.g. the Spanish version of `security.md` would be `security.es.md`).
 
 This configuration allows the language switcher to take the user to the translation of the current URL. If a translation doesn't exist, the 404 page will be displayed, with an explanation in each language set in the config.
 
+To learn more about multilingual support, see the [Frequently Asked Questions](https://welpo.github.io/tabi/blog/faq-languages/).
+
 ## Inspiration
 
 This theme was inspired by:
@@ -130,7 +133,9 @@ This theme was inspired by:
 
 ## Contributing
 
-Please do! Take a look at the [Contributing Guidelines](/CONTRIBUTING.md) to learn more.
+Please do! We appreciate bug reports, improvements to translations or documentation (however minor), feature requests…
+
+Take a look at the [Contributing Guidelines](/CONTRIBUTING.md) to learn more.
 
 ## License
 

diff --git a/config.toml b/config.toml
@@ -6,142 +6,36 @@ generate_feed = true
 compile_sass = true
 minify_html = true
 
-default_language = "en"
+# To translate the entire theme, there must be a file with the same ISO 639-1 Code
+# in the `i18n` folder of your site or the tabi theme (e.g. "i18n/fr.toml" for French).
+# Otherwise the theme will be in English.
+# See https://welpo.github.io/tabi/blog/faq-languages/ for more details.
+default_language = "ko"
 
-taxonomies = [
-    {name = "tags", feed = true},
-]
+taxonomies = [{name = "tags", feed = true}]
 
 [markdown]
 external_links_target_blank = true
 highlight_code = true
 highlight_theme = "css"
 
-default_language = "en"
-
 [languages.es]
 title = "~/tabi"
 description = "tabi es un tema de Zola rápido, liviano y moderno con JavaScript opcional y una puntuación perfecta en Lighthouse."
 generate_feed = true
 compile_sass = true
 minify_html = true
-
-taxonomies = [
-    {name = "tags", feed = true},
-]
+taxonomies = [{name = "tags", feed = true}]
 
 [languages.ca]
 title = "~/tabi"
 description = "tabi és un tema de Zola ràpid, lleuger i modern amb JavaScript opcional i una puntuació perfecta a Lighthouse."
 generate_feed = true
 compile_sass = true
 minify_html = true
-
-taxonomies = [
-    {name = "tags", feed = true},
-]
-
-[languages.es.translations]
-language_name = "Español"
-date_locale = "es_ES"
-# Menu items.
-blog = "blog"
-archive = "archivo"
-tags = "etiquetas"
-words = "palabras"
-projects = "proyectos"
-# Other text.
-tags_title = "Todas las etiquetas"
-404_error = "La página que has solicitado parece no existir o aún no se ha traducido a tu idioma. Revisa la URL en busca de errores o"
-go_home = "regresa a la página de inicio"
-read_more = "Leer más"
-all_posts = "Todas las entradas"
-all_tags = "Todas las etiquetas"
-min_read = "min de lectura"
-powered_by = "Impulsado por"
-and = "y"
-post = "entrada"
-posts = "entradas"
-prev = "Anterior"
-next = "Siguiente"
-of = "de"
-draft = "BORRADOR"
-table_of_contents = "Tabla de contenido"
-last_updated_on = "Última actualización el"
-show_original_quote = "Mostrar cita original"
-show_translation = "Mostrar traducción"
-load_comments = "Cargar comentarios"
-see_changes = "Ver cambios"
-site_source = "Código del sitio"
-# Quotation marks for multilingual quote shortcode.
-open_quotation_mark = "«"
-close_quotation_mark = "»"
-# Translations for stylised Atom feed.
-this_is_a_web_feed = "Esta es una fuente web"
-also_known_as_an_Atom_feed = "también conocida como fuente Atom"
-subscribe = "Suscríbete"
-by_copying_the_URL_from_the_address_bar_into_your_newsreader = "copiando la URL de la barra de direcciones en tu lector de noticias"
-visit = "Visita"
-to_learn_more_and_get_started = "para aprender más y empezar"
-it_s_free = "Es gratis"
-website = "la web"
-recent_posts = "Publicaciones recientes"
-
-[languages.ca.translations]
-language_name = "Català"
-date_locale = "ca_ES"
-# Menu items.
-blog = "blog"
-archive = "arxiu"
-tags = "etiquetes"
-words = "paraules"
-projects = "projectes"
-# Other text.
-tags_title = "Totes les etiquetes"
-404_error = "La pàgina que has sol·licitat sembla que no existeix o encara no s'ha traduït al teu idioma. Comprova l'URL per detectar errors o"
-go_home = "torna a la pàgina d'inici"
-read_more = "Llegir més"
-all_posts = "Totes les entrades"
-all_tags = "Totes les etiquetes"
-min_read = "min de lectura"
-powered_by = "Propulsat per"
-and = "i"
-post = "entrada"
-posts = "entrades"
-prev = "Anterior"
-next = "Següent"
-of = "de"
-draft = "ESBORRANY"
-table_of_contents = "Taula de contingut"
-last_updated_on = "Última actualizació el"
-show_original_quote = "Mostra la cita original"
-show_translation = "Mostra la traducció"
-load_comments = "Carregar comentaris"
-see_changes = "Veure canvis"
-site_source = "Codi del lloc"
-# Quotation marks for multilingual quote shortcode.
-open_quotation_mark = "«"
-close_quotation_mark = "»"
-# Translations for stylised Atom feed.
-this_is_a_web_feed = "Aquest és un canal web"
-also_known_as_an_Atom_feed = "també conegut com a canal Atom"
-subscribe = "Subscriu-te"
-by_copying_the_URL_from_the_address_bar_into_your_newsreader = "copiant l'URL de la barra d'adreces al teu lector de notícies"
-visit = "Visita"
-to_learn_more_and_get_started = "per aprendre més i començar"
-it_s_free = "És gratuït"
-website = "la web"
-recent_posts = "Publicacions recents"
+taxonomies = [{name = "tags", feed = true}]
 
 [extra]
-
-# Languages for your site.
-# Each should have a translation section above.
-# e.g. [languages.ca.translations]
-language_name.ca = "Català"
-language_name.en = "English"
-language_name.es = "Español"
-
 # Enable JavaScript theme toggler to allow users to switch between dark/light mode.
 # Also enables automatic switching based on user's OS-level theme settings.
 # If disabled, your site will only use the theme specified in the `default_theme` variable.

diff --git a/content/blog/faq-languages.ca.md b/content/blog/faq-languages.ca.md
@@ -0,0 +1,129 @@
++++
+title = "Lost in Translation? Explora les capacitats multilingües de tabi"
+date = 2023-09-12
+description = "Descobreix com tabi t'ajuda a connectar amb una audiència global gràcies a les seves funcions multilingües. Aprèn a canviar la llengua per defecte, afegir més llengües i aportar les teves pròpies traduccions."
+
+[taxonomies]
+tags = ["funcionalitat", "tutorial", "Preguntes Freqüents"]
+
+[extra]
+quick_navigation_buttons = true
+toc_ignore_pattern = "^(Preguntes Freqüents)"
++++
+
+tabi simplifica el procés de creació de llocs web multilingües perquè puguis connectar amb una audiència global. En aquesta guia, t'explicarem tot el que necessites saber, des de com configurar la llengua principal en el teu lloc fins a com contribuir amb les teves pròpies traduccions. Comencem!
+
+### Preguntes Freqüents
+
+<!-- toc -->
+
+## Quines llengües admet tabi?
+
+tabi admet les següents llengües:
+
+- Alemany
+- Anglès
+- Català
+- Coreà
+- Espanyol
+- Francès
+- Hindi
+- Italià
+- Japonès
+- Portuguès (Europeu)
+- Rus
+- Ucraïnès
+- Xinès (Simplificat)
+
+Per a una llista sempre actualitzada de llengües suportades, consulta la [carpeta `i18n`](https://github.com/welpo/tabi/tree/main/i18n) en el repositori de tabi.
+
+## Com estableixo la llengua predeterminada del meu lloc?
+
+Pots definir la llengua principal del teu lloc configurant la variable `default_language` a `config.toml`.
+
+Per exemple, si vols que la llengua principal sigui el Xinès, simplement afegeix aquesta línia a l'arxiu `config.toml`:
+
+```toml, hl_lines=03
+base_url = "https://welpo.github.io/tabi"
+title = "~/tabi"
+default_language = "zh"
+```
+
+tabi es traduirà a aquesta llengua, si està suportada.
+
+## Com gestiona tabi el suport multilingüe?
+
+Zola genera automàticament URLs per a cada llengua que no sigui la predeterminada de la següent manera: `{base_url}/{codi_idioma}/{post}`.
+
+tabi facilita la navegació entre llengües afegint un commutador de llengua en la barra de navegació (que només es mostra quan hi ha més d'una llengua habilitada).
+
+Si [pujes](#) a la barra de navegació, veuràs el commutador de llengua. En passar el cursor sobre ell, es mostrarà un desplegable amb les llengües disponibles. Si fas clic en el nom d'una llengua, et portarà a la mateixa pàgina en aquesta llengua.
+
+Si una pàgina específica no està disponible en una llengua, tabi mostrarà una pàgina 404 amb el text:
+
+> La pàgina que has sol·licitat sembla que no existeix o encara no s'ha traduït al teu idioma. Comprova l'URL per detectar errors o torna a la pàgina d'inici.
+
+Aquest text es mostrarà una vegada per cada llengua activada en el teu lloc. Pots veure aquesta pàgina en acció [aquí](https://welpo.github.io/tabi/404.html).
+
+## Com activo el suport multilingüe?
+
+Per habilitar el suport per a diverses llengües, necessites configurar la variable `languages` a `config.toml`. Per exemple, si vols un lloc amb anglès com a llengua principal que també admeti hindi i espanyol, pots configurar el teu `config.toml` de la següent manera:
+
+```toml
+base_url = "https://example.com"
+title = "My Site"
+default_language = "en"
+
+[languages.hi]
+title = "मेरी वेबसाइट"
+
+[languages.es]
+title = "El meu web"
+```
+
+En cada secció de llengua pots establir altres variables com `taxonomies`, `description`… Consulta la [documentació de suport multilingüe de Zola](https://www.getzola.org/documentation/content/multilingual/) per a més informació.
+
+## Què són aquests codis de dues lletres?
+
+Els codis de dues lletres són [codis d'idioma ISO 639-1](https://localizely.com/iso-639-1-list/), que serveixen per identificar idiomes d'una manera estandarditzada.
+
+tabi utilitza aquests codis per permetre la navegació entre idiomes i traduir el tema.
+
+## Com personalitzo o reemplaço una cadena de text específica al meu lloc web?
+
+tabi cerca els fitxers de cadenes en el següent ordre. `$base_directory` és on resideix el teu lloc Zola (allà on està `config.toml`):
+
+1. `$base_directory + "i18n"`
+2. `$base_directory + "themes/tabi/i18n"`
+
+Per tant, si crees `i18n/ca.toml` al teu directori base, tabi llegirà les cadenes de text d'aquest fitxer en lloc de les cadenes predeterminades en català. Pots fer això per a qualsevol idioma, suportat o no.
+
+Assegura't de copiar tot el fitxer per a aquest idioma primer, o el tema utilitzarà l'anglès per les claus que faltin.
+
+## Què passa si falta una traducció o està incompleta?
+
+Si una cadena no es troba en el fitxer d'idioma, tabi recorrerà a la cadena predeterminada en català.
+
+## El meu idioma no està suportat. Puc contribuir amb una traducció?
+
+És clar! Sempre estem buscant afegir suport per a més idiomes. Pots contribuir amb una traducció creant una Pull Request al [repositori de tabi](https://github.com/welpo/tabi).
+
+Pots utilitzar el [fitxer en català](https://github.com/welpo/tabi/blob/main/i18n/ca.toml) com a base per traduir les cadenes al teu idioma. Assegura't de mantenir la mateixa estructura.
+
+El fitxer ha de portar el nom del codi de dues lletres del teu idioma i ha de ser un fitxer TOML. Per exemple, si vols afegir suport per al suahili, pots crear un fitxer anomenat `sw.toml` al directori `i18n`.
+
+Nota: quan provis la teva traducció, és possible que necessitis reiniciar `zola serve` per veure els canvis, ja que Zola no sempre detecta canvis en els fitxers TOML.
+
+## He trobat un error en una traducció. Com el corregeixo?
+
+Si trobes un error en una traducció, pots crear un problema o una sol·licitud d'extracció al [repositori de tabi](https://github.com/welpo/tabi).
+
+## Com actualitzo les traduccions després d'una actualització del tema?
+
+Si no vas personalitzar les traduccions, simplement actualitza el tema.
+
+Si ho vas fer, hauràs d'actualitzar manualment les traduccions. Pots fer-ho copiant les noves cadenes dels fitxers corresponents i enganxant-les al teu fitxer personalitzat.
+
+## tabi tradueix el meu contingut?
+
+No. tabi només tradueix les cadenes de text del tema. Hauràs de traduir el teu contingut tu mateix.