MJML - Lingo.dev CLI

Qu'est-ce que MJML ?

MJML (Mailjet Markup Language) est un framework d'e-mails responsive qui facilite la création de modèles d'e-mails adaptatifs. Il utilise une syntaxe sémantique qui simplifie le développement d'e-mails responsive et compile en HTML standard compatible avec tous les principaux clients de messagerie.

Qu'est-ce que Lingo.dev CLI ?

Lingo.dev CLI est un outil en ligne de commande 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 modèles d'e-mails MJML 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 modèle MJML contenant le contenu à traduire. Ces fichiers doivent être situés à 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 example_en.mjml).

Pour les modèles MJML, le contenu traduisible comprend :

Contenu textuel dans les composants MJML :
- mj-text (texte du corps)
- mj-button (libellés de bouton)
- mj-title (titre de l'e-mail dans l'aperçu)
- mj-preview (texte d'aperçu)
- mj-navbar-link (liens de navigation)
- mj-accordion-title (en-têtes d'accordéon)
- mj-accordion-text (contenu d'accordéon)
Éléments HTML dans MJML : p, h1-h6, li
Valeurs d'attributs incluant :
- Attributs alt et title sur mj-image
- Attributs title et aria-label sur mj-button
- Attributs title et alt sur mj-social-element
- Attributs alt et title sur les éléments HTML img et a

Comment le HTML en ligne est géré :

Lorsque le texte contient des éléments HTML en ligne (tels que , , , <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 :

<mj-text>
  <p>Welcome to <strong>our platform</strong>!</p>
</mj-text>

L'ensemble du paragraphe "Welcome to our platform!" est traduit comme un seul bloc, en conservant les balises  en place. Cela garantit que le traducteur IA dispose du contexte complet et que le formatage en ligne est préservé dans la traduction.

Les variables de template (comme les variables Razor @Model.UserName) sont préservées pendant la traduction.

Étape 5. Créer un bucket

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

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

Dans l'objet "mjml", 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": {
    "mjml": {
      "include": ["./[locale]/example.mjml"]
    }
  }
}
```
Ces motifs définissent quels 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]/example.mjml")
- peuvent utiliser des astérisques comme espaces réservés génériques (par exemple, "[locale]/*.mjml")
Les motifs glob récursifs (par exemple, **/*.mjml) 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 :

Créez un compte Lingo.dev.
Exécutez la commande suivante :
```
npx lingo.dev@latest login
```
Cela ouvrira votre navigateur par défaut et vous demandera de vous authentifier.
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 :

Lit le fichier i18n.json.
Trouve les fichiers qui doivent être traduits.
Extrait le contenu traduisible des fichiers.
Utilise le LLM configuré pour traduire le contenu extrait.
É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.mjml

<?xml version="1.0" encoding="UTF-8"?>
<mjml>
  <mj-head>
    <mj-title>Welcome to Our Service</mj-title>
    <mj-preview>Get started with your new account today</mj-preview>
    <mj-attributes>
      <mj-all font-family="Arial, sans-serif" />
    </mj-attributes>
  </mj-head>
  <mj-body>
    <mj-section background-color="#f0f0f0">
      <mj-column>
        <mj-image
          src="https://example.com/logo.png"
          alt="Company Logo"
          width="150px"
        />
      </mj-column>
    </mj-section>

    <mj-section background-color="#ffffff" padding="20px">
      <mj-column>
        <mj-text font-size="24px" color="#333333" font-weight="bold">
          Welcome to Our Platform!
        </mj-text>
        <mj-text font-size="16px" color="#555555" line-height="24px">
          Thank you for signing up. We're excited to have you on board.
        </mj-text>
        <mj-text font-size="16px" color="#555555" line-height="24px">
          To get started, please verify your email address by clicking the
          button below.
        </mj-text>
      </mj-column>
    </mj-section>

    <mj-section background-color="#ffffff" padding="20px">
      <mj-column>
        <mj-button
          background-color="#007bff"
          color="#ffffff"
          href="https://example.com/verify"
          title="Verify your email address"
          aria-label="Verify email"
        >
          Verify Email Address!
        </mj-button>
      </mj-column>
    </mj-section>

    <mj-section background-color="#ffffff" padding="20px">
      <mj-column>
        <mj-text font-size="14px" color="#666666">
          If you didn't create an account, you can safely ignore this email.
        </mj-text>
        <mj-text font-size="14px" color="#666666">
          Need help? Contact our support team.
        </mj-text>
      </mj-column>
    </mj-section>

    <mj-section background-color="#f8f9fa" padding="20px">
      <mj-column>
        <mj-social mode="horizontal">
          <mj-social-element
            name="facebook"
            href="https://facebook.com/example"
            title="Follow us on Facebook"
            alt="Facebook"
          />
          <mj-social-element
            name="twitter"
            href="https://twitter.com/example"
            title="Follow us on Twitter"
            alt="Twitter"
          />
          <mj-social-element
            name="instagram"
            href="https://instagram.com/example"
            title="Follow us on Instagram"
            alt="Instagram"
          />
        </mj-social>
        <mj-text font-size="12px" color="#999999" align="center">
          © 2024 Example Company. All rights reserved.
        </mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

es/example.mjml

<?xml version="1.0" encoding="UTF-8"?>
<mjml>
  <mj-head>
    <mj-title>Bienvenido a nuestro servicio</mj-title>
    <mj-preview>Comienza con tu nueva cuenta hoy</mj-preview>
    <mj-attributes>
      <mj-all font-family="Arial, sans-serif" />
    </mj-attributes>
  </mj-head>
  <mj-body>
    <mj-section background-color="#f0f0f0">
      <mj-column>
        <mj-image
          src="https://example.com/logo.png"
          alt="Logo de la empresa"
          width="150px"
        />
      </mj-column>
    </mj-section>

    <mj-section background-color="#ffffff" padding="20px">
      <mj-column>
        <mj-text font-size="24px" color="#333333" font-weight="bold">
          ¡Bienvenido a nuestra plataforma!
        </mj-text>
        <mj-text font-size="16px" color="#555555" line-height="24px">
          Gracias por registrarte. Estamos encantados de tenerte con nosotros.
        </mj-text>
        <mj-text font-size="16px" color="#555555" line-height="24px">
          Para comenzar, por favor verifica tu dirección de correo electrónico
          haciendo clic en el botón de abajo.
        </mj-text>
      </mj-column>
    </mj-section>

    <mj-section background-color="#ffffff" padding="20px">
      <mj-column>
        <mj-button
          background-color="#007bff"
          color="#ffffff"
          href="https://example.com/verify"
          title="Verifica tu dirección de correo electrónico"
          aria-label="Verificar correo"
        >
          ¡Verificar dirección de correo!
        </mj-button>
      </mj-column>
    </mj-section>

    <mj-section background-color="#ffffff" padding="20px">
      <mj-column>
        <mj-text font-size="14px" color="#666666">
          Si no creaste una cuenta, puedes ignorar este correo electrónico.
        </mj-text>
        <mj-text font-size="14px" color="#666666">
          ¿Necesitas ayuda? Contacta a nuestro equipo de soporte.
        </mj-text>
      </mj-column>
    </mj-section>

    <mj-section background-color="#f8f9fa" padding="20px">
      <mj-column>
        <mj-social mode="horizontal">
          <mj-social-element
            name="facebook"
            href="https://facebook.com/example"
            title="Síguenos en Facebook"
            alt="Facebook"
          />
          <mj-social-element
            name="twitter"
            href="https://twitter.com/example"
            title="Síguenos en Twitter"
            alt="Twitter"
          />
          <mj-social-element
            name="instagram"
            href="https://instagram.com/example"
            title="Síguenos en Instagram"
            alt="Instagram"
          />
        </mj-social>
        <mj-text font-size="12px" color="#999999" align="center">
          © 2024 Example Company. Todos los derechos reservados.
        </mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

i18n.json

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

i18n.lock

version: 1
checksums:
  c1acde0589961652d4caf8a39d080857:
    mjml/mj-head/0/mj-title/0: c514a686b50f7158b2dd08ea65d3bc8a
    mjml/mj-head/0/mj-preview/0: 4ce14f6062c814cbdcdf8b0a3cb094d3
    mjml/mj-body/0/mj-section/0/mj-column/0/mj-image/0#alt: 82d5c0d5994508210ee02d684819f4b8
    mjml/mj-body/0/mj-section/1/mj-column/0/mj-text/0: b320b02942617a70dcbd1beac61da11a
    mjml/mj-body/0/mj-section/1/mj-column/0/mj-text/1: 028311348a5aeefea365fdf422a3fb21
    mjml/mj-body/0/mj-section/1/mj-column/0/mj-text/2: 0dfdc9b80ee70fcc2b28d0e81e03fabc
    mjml/mj-body/0/mj-section/2/mj-column/0/mj-button/0#title: 5c96f738bd6153ee07b72094cdfd2b98
    mjml/mj-body/0/mj-section/2/mj-column/0/mj-button/0#aria-label: 42dcab68d931f9145d9b6d76740a5c66
    mjml/mj-body/0/mj-section/2/mj-column/0/mj-button/0: dc8001d5c58294d22fe0b0e6118dbfb7
    mjml/mj-body/0/mj-section/3/mj-column/0/mj-text/0: a18f14ab69467cbdbe467df6255cfda7
    mjml/mj-body/0/mj-section/3/mj-column/0/mj-text/1: e83236e98aad1937bc99a47cff159caa
    mjml/mj-body/0/mj-section/4/mj-column/0/mj-social/0/mj-social-element/0#title: 180bd8aa700f6cedf65e0a2079503cea
    mjml/mj-body/0/mj-section/4/mj-column/0/mj-social/0/mj-social-element/0#alt: ac8afe226a7424849c247e6a9d566f64
    mjml/mj-body/0/mj-section/4/mj-column/0/mj-social/0/mj-social-element/1#title: ea4c2a7a9a60cbb0f8f9632222a46abe
    mjml/mj-body/0/mj-section/4/mj-column/0/mj-social/0/mj-social-element/1#alt: ba3d4aed69a50759b53a0b7c319a3ad9
    mjml/mj-body/0/mj-section/4/mj-column/0/mj-social/0/mj-social-element/2#title: 754efa5f98f51c510ff268e217877d8b
    mjml/mj-body/0/mj-section/4/mj-column/0/mj-social/0/mj-social-element/2#alt: c9555810826c30d571ffae869a236494
    mjml/mj-body/0/mj-section/4/mj-column/0/mj-text/0: 9ac6c625c7af33d70634846c8c9d11b0