Traduire le contenu des add-ons

Vue d'ensemble

Chaque add-on Larapen (Blog, Boutique, Support, etc.) est livré avec son propre ensemble de fichiers de traduction, séparés de l'application principale. Ce guide explique comment localiser, traduire et synchroniser les traductions des add-ons.

Où se trouvent les fichiers de traduction des add-ons

Les traductions des add-ons suivent le même format de tableau PHP que les traductions du cœur, mais elles se trouvent dans le répertoire de chaque add-on :

extensions/addons/{nom-addon}/resources/lang/
├── en/
│   └── {nom-addon}.php      ← Traductions anglaises (référence)
├── fr/
│   └── {nom-addon}.php      ← Traductions françaises
└── de/
    └── {nom-addon}.php      ← Traductions allemandes (après ajout de l'allemand)

Exemples

extensions/addons/blog/resources/lang/en/blog.php
extensions/addons/blog/resources/lang/fr/blog.php

extensions/addons/shop/resources/lang/en/shop.php
extensions/addons/shop/resources/lang/fr/shop.php

extensions/addons/helpcenter/resources/lang/en/helpcenter.php
extensions/addons/helpcenter/resources/lang/fr/helpcenter.php

Fonctionnement des traductions d'add-ons

Création automatique

Lorsque vous ajoutez une nouvelle langue dans le panneau d'administration (Paramètres → Langues → Ajouter une langue), Larapen automatiquement :

1. Analyse tous les add-ons installés dans extensions/addons/.
2. Pour chaque add-on possédant un répertoire de traduction en/, copie ces fichiers vers le répertoire de la nouvelle langue.
3. Les fichiers copiés contiennent le texte anglais comme espace réservé, prêt à être traduit.

Par exemple, si vous ajoutez l'allemand (de) et que vous avez les add-ons Blog et Boutique installés, Larapen crée :

• extensions/addons/blog/resources/lang/de/blog.php
• extensions/addons/shop/resources/lang/de/shop.php

Format des clés de traduction

Les traductions des add-ons utilisent un format avec espace de noms. L'espace de noms est le nom de l'add-on :

// Dans les templates Blade et le code PHP, les traductions des add-ons sont accessibles via :
__('blog::blog.posts.title')          // Add-on Blog : clé "posts.title"
__('shop::shop.products.add_to_cart') // Add-on Boutique : clé "products.add_to_cart"
__('helpcenter::helpcenter.tickets.new')  // Add-on Support : clé "tickets.new"

Le double deux-points (::) sépare l'espace de noms de l'add-on de la clé de traduction. Vous n'avez pas besoin de vous en soucier lors de la traduction: traduisez simplement les valeurs dans les fichiers PHP.

Comment traduire les fichiers d'add-ons

Étape 1 : Localiser le fichier

Naviguez vers le répertoire de traduction de l'add-on :

extensions/addons/{nom-addon}/resources/lang/{votre-code-langue}/

Ouvrez le fichier PHP dans un éditeur de texte.

Étape 2 : Traduire les valeurs

La structure du fichier est identique aux fichiers de traduction du cœur: un tableau PHP où vous remplacez les valeurs anglaises par vos traductions :

<?php

declare(strict_types=1);

return [
    'posts' => [
        'title'       => 'Blog Posts',      // ← Remplacer par la traduction
        'add_new'     => 'New Post',         // ← Remplacer par la traduction
        'edit'        => 'Edit Post',        // ← Remplacer par la traduction
        'published'   => 'Published',        // ← Remplacer par la traduction
        'draft'       => 'Draft',            // ← Remplacer par la traduction
        'view_count'  => ':count views',     // ← Garder l'espace réservé :count !
    ],
    'categories' => [
        'title'       => 'Categories',
        'add_new'     => 'New Category',
    ],
    // ...
];

Étape 3 : Enregistrer en encodage UTF-8

Enregistrez toujours le fichier en encodage UTF-8 (sans BOM) pour que les caractères spéciaux s'affichent correctement.

Garder les traductions d'add-ons synchronisées

Lorsqu'un add-on est mis à jour vers une nouvelle version, il peut inclure de nouvelles clés de traduction dans ses fichiers anglais. Pour synchroniser toutes les langues :

1. Allez dans Paramètres → Langues dans le panneau d'administration.
2. Cliquez sur « Synchroniser les fichiers de traduction ».

Cela va :

• Ajouter toute nouvelle clé des fichiers anglais de l'add-on à toutes les autres langues (avec le texte anglais comme espace réservé).
• Supprimer toute clé obsolète qui n'existe plus dans les fichiers anglais.
• Préserver toutes les traductions existantes dans chaque langue.
• Traiter tous les add-ons installés en une seule opération.

Traduction par IA pour les add-ons

La fonctionnalité de traduction automatique par IA (disponible dans Paramètres → Langues) traduit également les fichiers des add-ons. Lorsque vous cliquez sur « Traduction IA » pour une langue, le système traite à la fois les fichiers de traduction du cœur et des add-ons en une seule opération. C'est le moyen le plus rapide de traduire tout le contenu des add-ons pour une nouvelle langue.

Traductions d'add-ons et thèmes

Les fichiers de traduction des add-ons sont indépendants des thèmes. Lorsque vous changez de thème, les mêmes traductions d'add-ons sont utilisées quel que soit le thème actif. Le thème contrôle la présentation visuelle (mise en page, styles), tandis que les fichiers de traduction contrôlent le contenu textuel.

Priorité de traduction

Lorsque Larapen recherche une traduction pour un add-on, il vérifie dans cet ordre :

1. Fichier de traduction de l'add-on pour la langue actuelle: extensions/addons/{addon}/resources/lang/{locale}/{addon}.php
2. Fichier de traduction de l'add-on pour la langue de repli (généralement l'anglais): extensions/addons/{addon}/resources/lang/en/{addon}.php
3. Si aucune traduction n'est trouvée, la clé de traduction elle-même est affichée.

Dépannage

Traduction non affichée

• Vérifiez que le fichier existe au bon chemin : extensions/addons/{addon}/resources/lang/{code}/{addon}.php
• Vérifiez que le fichier retourne un tableau PHP valide (pas d'erreurs de syntaxe).
• Videz le cache de l'application : Paramètres → Cache → Tout vider.

Fichiers de traduction manquants pour une nouvelle langue

• Exécutez « Synchroniser les fichiers de traduction » depuis Paramètres → Langues.
• Ou copiez manuellement le répertoire en/ vers votre nouveau code de langue : cp -r extensions/addons/{addon}/resources/lang/en/ extensions/addons/{addon}/resources/lang/{code}/

Add-on installé après la création de la langue

Si vous installez un add-on après avoir déjà ajouté une langue, les fichiers de traduction de l'add-on n'ont peut-être pas été créés pour cette langue. Exécutez simplement « Synchroniser les fichiers de traduction » pour créer les fichiers manquants.