Twig

Traduction IA pour les templates Twig avec Lingo.dev CLI

Qu'est-ce que Twig ?

Twig est un moteur de templates flexible, rapide et sécurisé pour PHP. Il est largement utilisé dans les applications Symfony et d'autres frameworks PHP pour séparer la logique de présentation de la logique applicative. Twig utilise une syntaxe claire qui rend les templates faciles à lire et à écrire.

Qu'est-ce que Lingo.dev CLI ?

Lingo.dev CLI est un CLI gratuit et open source pour traduire des applications et du contenu avec l'IA. Il est conçu pour remplacer les logiciels de gestion de traduction traditionnels tout en s'intégrant aux pipelines existants.

Pour en savoir plus, consultez Présentation.

À propos de ce guide

Ce guide explique comment traduire des templates Twig avec Lingo.dev CLI.

Vous apprendrez à :

  • Créer un projet à partir de zéro
  • Configurer un pipeline de traduction
  • Générer des traductions avec l'IA

Prérequis

Pour utiliser Lingo.dev CLI, assurez-vous que Node.js v18+ est installé :

❯ node -v
v22.17.0

Étape 1. Configurer un projet

Dans le répertoire de votre projet, créez un fichier i18n.json :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Ce fichier définit le comportement du pipeline de traduction, notamment les langues entre lesquelles traduire et l'emplacement du contenu localisable sur le système de fichiers.

Pour en savoir plus sur les propriétés disponibles, consultez i18n.json.

Étape 2. Configurer la locale source

La locale source est la langue et la région d'origine dans lesquelles votre contenu a été rédigé. Pour configurer la locale source, définissez la propriété locale.source dans le fichier i18n.json :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

La locale source doit être fournie sous forme de balise de langue BCP 47.

Pour la liste complète des codes de locale pris en charge par Lingo.dev CLI, consultez Codes de locale pris en charge.

Étape 3. Configurer les locales cibles

Les locales cibles sont les langues et régions vers lesquelles vous souhaitez traduire votre contenu. Pour configurer les locales cibles, définissez la propriété locale.targets dans le fichier i18n.json :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Étape 4. Créer le contenu source

Si ce n'est pas déjà fait, créez un ou plusieurs fichiers de template Twig contenant le contenu à traduire. Ces fichiers doivent être situés dans un chemin qui inclut la locale source quelque part dans le chemin (par exemple, comme nom de répertoire tel que en/ ou comme partie du nom de fichier tel que template_en.html.twig).

Pour les templates Twig, le contenu traduisible comprend :

  • Le contenu textuel dans les éléments de bloc : h1-h6, p, div, li, blockquote, article, section, etc.
  • Le contenu textuel dans les éléments en ligne : a, strong, em, span, code, etc.
  • Les valeurs d'attributs incluant :
    • L'attribut content sur les balises meta
    • Les attributs alt et title sur les balises img
    • Les attributs placeholder, title et aria-label sur les balises input, textarea, button, a, abbr et link

Comment la syntaxe Twig est gérée :

La syntaxe des templates Twig est entièrement préservée pendant la traduction :

  • Les variables et expressions Twig ({{ user.name }}, {{ product.price|number_format }}) sont conservées telles quelles dans le texte traduisible
  • Les structures de contrôle Twig ({% if %}, {% for %}, {% set %}) sont préservées et non traduites
  • Les commentaires Twig ({# internal note #}) sont préservés et non traduits
  • Les filtres Twig ({{ "now"|date('Y') }}) restent fonctionnels dans les templates traduits

Comment le HTML en ligne est géré :

Lorsque le texte contient des éléments HTML en ligne (tels que <strong>, <span>, <em>, <a>, etc.), l'ensemble du bloc de texte est traduit comme une unité complète. Cela préserve le contexte pour une meilleure qualité de traduction et maintient le formatage en ligne.

Par exemple :

<p>Hello <strong>{{ user.name }}</strong>, welcome back!</p>

L'intégralité du paragraphe "Hello <strong>{{ user.name }}</strong>, welcome back!" est traduite comme un bloc unique, en conservant à la fois les balises <strong> et la variable Twig en place. Cela garantit que le traducteur IA dispose du contexte complet et que la mise en forme inline et la syntaxe Twig sont préservées dans la traduction.

Attribut lang automatique :

L'attribut lang sur l'élément <html> est automatiquement mis à jour pour correspondre à la locale cible :

<!-- Source (en/template.html.twig) -->
<html>
<head>
    <title>Welcome</title>
</head>

<!-- Target (es/template.html.twig) -->
<html lang="es">
<head>
    <title>Bienvenido</title>
</head>

Contenu non traduisible :

Le contenu à l'intérieur des balises <script> et <style> n'est pas traduit.

Étape 5. Créer un bucket

  1. Dans le fichier i18n.json, ajoutez un objet "twig" à l'objet buckets :

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "twig": {}
  }
}

  2. Dans l'objet "twig", définissez un tableau d'un ou plusieurs motifs include :

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "twig": {
      "include": ["./[locale]/*.twig"]
    }
  }
}

    Ces motifs définissent les fichiers à traduire.

    Les motifs eux-mêmes :

    • doivent contenir [locale] comme espace réservé pour la locale configurée
    • peuvent pointer vers des chemins de fichiers (par exemple, "[locale]/template.html.twig")
    • peuvent utiliser des astérisques comme espaces réservés génériques (par exemple, "[locale]/*.twig")

    Les motifs glob récursifs (par exemple, **/*.twig) ne sont pas pris en charge.

Étape 6. Configurer un LLM

Lingo.dev CLI utilise des modèles de langage de grande taille (LLM) pour traduire le contenu avec l'IA. Pour utiliser l'un de ces modèles, vous avez besoin d'une clé API d'un fournisseur pris en charge.

Pour démarrer le plus rapidement possible, nous recommandons d'utiliser Lingo.dev Engine :

  1. Créez un compte Lingo.dev.

  2. Exécutez la commande suivante :

    npx lingo.dev@latest login

    Cela ouvrira votre navigateur par défaut et vous demandera de vous authentifier.

  3. Suivez les instructions.

Étape 7. Générer les traductions

Dans le répertoire qui contient le fichier i18n.json, exécutez la commande suivante :

npx lingo.dev@latest run

Cette commande :

  1. Lit le fichier i18n.json.
  2. Trouve les fichiers qui doivent être traduits.
  3. Extrait le contenu traduisible des fichiers.
  4. Utilise le LLM configuré pour traduire le contenu extrait.
  5. Écrit le contenu traduit dans le système de fichiers.

La première fois que les traductions sont générées, un fichier i18n.lock est créé. Ce fichier garde une trace du contenu qui a été traduit, évitant ainsi les retraductions inutiles lors des exécutions suivantes.

Exemple

en/example.html.twig

{% set user = app.user %}
<!DOCTYPE html>
<html>
<head>
    <meta name="description" content="Welcome to our application">
    <title>Welcome</title>
</head>
<body>
    <header>
        <nav>
            <a href="/" title="Go to homepage">Home</a>
            <a href="/about" title="Learn more about us">About</a>
            <a href="/contact" title="Get in touch">Contact</a>
        </nav>
    </header>

    <main>
        <section class="hero">
            <h1>Welcome to Our Platform</h1>
            <p>Hello <strong>{{ user.name }}</strong>, we're glad to have you here!</p>
            <p>Start exploring our features and discover what makes us <em>unique</em>.</p>
        </section>

        {% if user.isPremium %}
        <section class="premium-benefits">
            <h2>Premium Benefits</h2>
            <ul>
                <li>Unlimited access to all features</li>
                <li>Priority customer support</li>
                <li>Advanced analytics and reporting</li>
            </ul>
        </section>
        {% endif %}

        <section class="getting-started">
            <h2>Getting Started</h2>
            <p>Follow these simple steps to begin your journey:</p>
            <ol>
                <li>Complete your profile</li>
                <li>Explore the dashboard</li>
                <li>Invite your team members</li>
            </ol>

            <form action="/profile/update" method="post">
                <label for="bio">Tell us about yourself:</label>
                <textarea id="bio" name="bio" placeholder="Enter your bio here" aria-label="User biography"></textarea>

                <label for="email">Email address:</label>
                <input type="email" id="email" name="email" placeholder="[email protected]" aria-label="Email address">

                <button type="submit" title="Save your profile changes">Save Profile</button>
            </form>
        </section>

        {# This section is for internal notes and won't be displayed #}
        {% if app.debug %}
        <section class="debug-info">
            <h3>Debug Information</h3>
            <p>User ID: {{ user.id }}</p>
            <p>Last login: {{ user.lastLogin|date('Y-m-d H:i:s') }}</p>
        </section>
        {% endif %}
    </main>

    <footer>
        <p>Need help? <a href="/support" title="Visit our support center">Contact Support</a></p>
        <p>&copy; {{ "now"|date('Y') }} Our Company. All rights reserved.</p>
    </footer>
</body>
</html>

es/example.html.twig

{% set user = app.user %}
<!DOCTYPE html>
<html lang="es">
<head>
    <meta name="description" content="Bienvenido a nuestra aplicación">
    <title>Bienvenido</title>
</head>
<body>
    <header>
        <nav><a href="/" title="Ir a la página de inicio">Inicio</a>
            <a href="/about" title="Conoce más sobre nosotros">Acerca de</a>
            <a href="/contact" title="Ponte en contacto">Contacto</a></nav>
    </header>

    <main>
        <section class="hero">
            <h1>Bienvenido a nuestra plataforma</h1>
            <p>Hola <strong>{{ user.name }}</strong>, nos alegra tenerte aquí!</p>
            <p>Comienza a explorar nuestras funciones y descubre lo que nos hace <em>únicos</em>.</p>
        </section>

        {% if user.isPremium %}
        <section class="premium-benefits">
            <h2>Beneficios premium</h2>
            <ul>
                <li>Acceso ilimitado a todas las funciones</li>
                <li>Soporte prioritario al cliente</li>
                <li>Análisis y reportes avanzados</li>
            </ul>
        </section>
        {% endif %}

        <section class="getting-started">
            <h2>Primeros pasos</h2>
            <p>Sigue estos sencillos pasos para comenzar tu experiencia:</p>
            <ol>
                <li>Completa tu perfil</li>
                <li>Explora el panel de control</li>
                <li>Invita a los miembros de tu equipo</li>
            </ol>

            <form action="/profile/update" method="post"><label for="bio">Cuéntanos sobre ti:</label>
                <textarea id="bio" name="bio" placeholder="Ingresa tu biografía aquí" aria-label="Biografía del usuario"></textarea>

                <label for="email">Dirección de correo electrónico:</label>
                <input type="email" id="email" name="email" placeholder="[email protected]" aria-label="Dirección de correo electrónico">

                <button type="submit" title="Guardar los cambios de tu perfil">Guardar perfil</button></form>
        </section>

        {# This section is for internal notes and won't be displayed #}
        {% if app.debug %}
        <section class="debug-info">
            <h3>Información de depuración</h3>
            <p>ID de usuario: {{ user.id }}</p>
            <p>Último inicio de sesión: {{ user.lastLogin|date('Y-m-d H:i:s') }}</p>
        </section>
        {% endif %}
    </main>

    <footer>
        <p>¿Necesitas ayuda? <a href="/support" title="Visita nuestro centro de soporte">Contacta con soporte</a></p>
        <p>© {{ "now"|date('Y') }} Nuestra empresa. Todos los derechos reservados.</p>
    </footer>
</body>
</html>

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "twig": {
      "include": ["./[locale]/*.twig"]
    }
  }
}

i18n.lock

version: 1
checksums:
  2d3d028d905803e471ca9f97a4969d5e:
    head/0#content: 1308168cca4fa5d8d7a0cf24e55e93fc
    head/1: 3180ad6b8de344b781637750259e0f53
    body/0/0: 9de5fe40cbf5f851a6d2270f01fe0739
    body/1/0/0: c59070fe496d5e4bd0066295b63a9056
    body/1/0/1: 12d74865332bf1988d51e84ba67aae09
    body/1/0/2: 58f0e438e665c77eedc440c5a8529b1a
    body/1/1/0: 119e3aa396d12a5a1aa7058e0983f9b9
    body/1/1/1/0: 60f9a22f4200bb4620a6ff7a1797ec30
    body/1/1/1/1: 03846a81f16f5e4a11acfd9445ad497d
    body/1/1/1/2: 15aae9d70ff1fb682f7d86baca81dcc0
    body/1/2/0: fbd403146395526d68ac68d142a50e21
    body/1/2/1: da8dc7fe06175d8b805f7f565bfe2788
    body/1/2/2/0: 061e1acc1b9ebad9de09fd5626e813c7
    body/1/2/2/1: 67f022a3f9e278d065a063b5e29dd932
    body/1/2/2/2: 7e23f048179f6661050edaa796528fe0
    body/1/2/3: 635f7e9a4afc00de34f975914afbb8b8
    body/1/3/0: 7a7892379e31868abba9865d20be2b72
    body/1/3/1: 8740df822561d74d51bb30e4b39d6193
    body/1/3/2: 0429f12258fabbde3abaca3dd9986178
    body/2/0: d32e57e4a5a65f3bee8b63dcb2bfa8e7
    body/2/1: 7e10a8ab9cc4e6d603b3cdc48849688f