Sélecteur de langues (Translate)

Utilisez le sélecteur de langues lorsqu’une page existe dans plusieurs langues.

attention

Ce composant nécessite une licence Pro valide en production.

Information	Valeur
Niveau	Pro
Composants Twig	dsfr:translate

Usage

• Indiquez la langue courante.
• Chaque lien doit pointer vers la version localisée.

Modes d'utilisation

Exemple principal

Sélecteur de langues · exemple principal

<twig:dsfr:translate
  id="language-selector"
  current="fr"
  currentLabel="Français"
  :languages="[
    {label: 'Français', href: '/fr', lang: 'fr', active: true},
    {label: 'English', href: '/en', lang: 'en'}
  ]"
/>

Données

La prop languages accepte un tableau PHP/Twig. En Twig, préfixez la prop par : pour transmettre une vraie structure de données.

Syntaxe typée Twig Component

{# Le préfixe : garde le type tableau/booléen/numérique. #}
<twig:dsfr:translate :languages="languages" />

Attributs HTML

Ajoutez vos attributs applicatifs directement sur le composant quand ils concernent le nœud racine rendu par le template.

Attributs pass-through

<twig:dsfr:translate
  id="selecteur-langues-example"
  class="fr-mt-2w"
  data-controller="selecteur-langues"
/>

API publique

Composant	Rôle
dsfr:translate	Composant principal de cette page.

Configuration

Option	Type	Défaut / requis	Valeurs et usage
id	string	Selon composant	Identifiant HTML, normalisé et utilisé par aria-controls quand nécessaire.
current	string	FR	Code de langue courant.
currentLabel	string	Français	Nom de la langue courante.
languages	array|string	[]	Langues { label, href, lang, active? }.
expanded	bool	false	Ouvre le menu au rendu initial.

Guide d'intégration

Question	Réponse
Famille DSFR	Navigation
Quand l'utiliser	Quand l’usager doit se repérer, changer de section ou parcourir une liste de pages.
Quand éviter	Pour déclencher une action métier immédiate : utilisez plutôt un bouton.
API publique	Utilisez uniquement les composants Twig listés sur cette page : dsfr:translate.
Documentation DSFR	Consultez aussi la bibliothèque officielle : Système de Design de l'État.

Sélecteur de langues : données typées via languages

Variantes de sélecteur de langues

• sélecteur de langues avec attributs HTML pass-through pour id, class, data-* et aria-* quand le template le permet.

Points de contrôle propres à ce composant

• Indiquez la langue courante.
• Chaque lien doit pointer vers la version localisée.
• Vérifiez un cas vide, un cas avec plusieurs entrées et un cas avec données dynamiques pour languages.
• Validez l’état ouvert, actif ou sélectionné au chargement et après interaction DSFR.

Accessibilité navigation

• Le libellé de navigation doit être explicite avec ariaLabel ou un titre visible.
• La page courante doit être indiquée avec active, current ou aria-current selon le composant.
• Les panneaux contrôlés par JavaScript DSFR doivent avoir des id uniques et stables.

Intégration Symfony/Twig pour dsfr:translate

• Passez languages avec la syntaxe : pour conserver le type tableau : :languages="languages".
• Ajoutez vos attributs applicatifs (data-controller, data-action, aria-*, class) sur dsfr:translate quand ils concernent son nœud racine.
• Gardez des id prévisibles pour dsfr:translate, surtout dans les listes ou formulaires répétés.

Checklist de recette

• navigation clavier complète
• état actif visible
• liaison aria-controls vers un élément existant
• rendu vérifié en thème clair et sombre ;
• rendu vérifié sur mobile, tablette et desktop ;
• aucune erreur dans le profiler DSFR ni dans l'inspecteur d'accessibilité du navigateur.

Erreurs fréquentes

Symptôme	Correction
Les données languages ne sont pas prises en compte	Ajoutez : devant la prop Twig : :languages.
Les classes DSFR semblent incomplètes	Utilisez les props du composant plutôt que des classes ajoutées à la main.
Un panneau, menu ou état actif ne fonctionne pas	Vérifiez que le JavaScript DSFR est chargé et que les identifiants HTML sont uniques.
Le composant rend en local mais pas en production	Vérifiez la licence avec php bin/console dsfr:license:validate.