Aller au contenu principal
Version: Next

Elementum Translator

Extension officielle Elementum pour la gestion des traductions de chaînes statiques. Dépend de Polylang.

Prérequis​

  • Framework Elementum
  • Plugin Polylang actif

Fonctionnement​

L'extension permet de déclarer dans un fichier YAML les chaînes de texte statiques d'un thème ou d'un plugin, de les saisir par langue depuis l'interface d'administration, et de les utiliser directement dans les templates Twig.

Déclaration des chaînes​

Chaque thème ou plugin déclare ses chaînes dans config/translations.yaml :

mon-theme:
    cookie_notice: "Ce site utilise des cookies pour améliorer votre expérience."
    cta_contact: "Contactez-nous"

La clé de premier niveau est le text domain du projet. Plusieurs projets peuvent coexister — Elementum fusionne automatiquement leurs chaînes.

Utilisation dans Twig​

Les traductions sont disponibles via la variable globale __t :

{{ __t.cookie_notice }}
{{ __t.cta_contact }}

La langue est détectée automatiquement via Polylang. Si aucune traduction n'est saisie, la valeur YAML est utilisée en fallback.

Sélecteur de langue​

{{ language_switcher() }}
{# Format abrégé : FR, EN… #}
{{ language_switcher(short=true) }}
{# Toutes les options #}
{{ language_switcher(show_names=true, show_flags=false, redirect=true, short=false) }}
ParamètreTypeDéfautDescription
show_namesbooltrueAffiche le nom complet de la langue
show_flagsboolfalseAffiche le drapeau Polylang
redirectbooltrueRedirige automatiquement à la sélection
shortboolfalseFormat abrégé (FR, EN…) — prend le dessus sur show_names

Champs Customize traduisibles​

Les champs du Customizer déclarés avec translate: true sont automatiquement enregistrés dans le système de traduction :

# customize/mon-panel.yaml
mon_panel:
    sections:
        hero:
            fields:
                titre_accueil:
                    type: text
                    label: "Titre d'accueil"
                    translate: true

Installation​

Clonez le plugin dans wp-content/plugins/ puis activez-le depuis l'interface WordPress :

git clone https://gitlab.com/devopress/framework/extension/elementum-translator.git wp-content/plugins/elementum-translator

Pour initialiser la configuration dans votre projet :

php dobby publish

Sélectionnez plugins/elementum-translator - translations pour copier le fichier d'exemple commenté dans votre dossier config/.

Debug​

Pour inspecter toutes les traductions résolues pour la langue courante, ajoutez debug: true dans config/translations.yaml :

debug: true

mon-theme:
    cookie_notice: "Ce site utilise des cookies."
    cta_contact: "Contactez-nous"

Quand ce flag est actif, le proxy est chargé immédiatement au hook wp (au lieu d'attendre le premier accès depuis un template). Toutes les traductions sont résolues et disponibles dès ce moment, ce qui permet de les inspecter directement dans Twig :

{{ dump(__t) }}

Ou depuis un controller via la façade Twig si besoin.

attention

Penser à retirer debug: true avant de passer en production.

Administration​

Les traductions se saisissent depuis WordPress Admin → Traductions. Chaque langue configurée dans Polylang dispose de sa colonne. La langue source (par défaut) est exclue — ses valeurs viennent du YAML.