Démarrage rapide

La force principale de Lingo.dev CLI est de localiser efficacement les applications et le contenu markdown dans les langues cibles à l'aide d'une seule commande CLI.

Ce guide de démarrage rapide suppose que vous êtes sur le point de rendre votre application multilingue, ou que vous l'avez déjà configurée pour gérer 2+ langues. Par conséquent, ce guide est conçu pour être suffisamment court pour être complété en moins de 10 minutes, mais suffisamment détaillé pour comprendre les mécanismes internes.

À la fin de ce guide, vous aurez :

1. Localisé le contenu de l'application en espagnol et en japonais à l'aide d'un moteur de traduction IA ;
2. Compris comment les fichiers source, les fichiers cibles et la configuration fonctionnent ensemble ;
3. Mis en place un flux de travail de localisation capable d'adapter votre application et votre contenu markdown à des dizaines de langues et des dizaines de milliers de mots.

Commençons !

Prérequis

Markdown

Les fichiers Markdown sont des documents structurés, ce qui signifie qu'aucune configuration préalable n'est nécessaire. Lingo.dev CLI traite directement les fichiers .md, en maintenant le formatage tout en localisant le contenu, vous pouvez donc passer à l'Étape 1.

Applications

Pour rendre une application multilingue, les applications web et mobiles modernes nécessitent que les développeurs configurent d'abord l'internationalisation (i18n).

Pour ce démarrage rapide, nous allons créer un fichier JSON autonome pour démontrer comment Lingo.dev CLI localise le contenu de l'application.

Lors de l'intégration avec votre application réelle, suivez nos guides de framework recommandés :

• React : react-intl
• Vue : vue-i18n
• Svelte : svelte-i18n
• Angular : ngx-translate
• iOS : Localizable.xcstrings
• Android : strings.xml

Étape 1. Initialiser le projet

Lingo.dev CLI utilise le fichier de configuration standard i18n.json pour déclarer vos paramètres de localisation. Pour le créer de manière interactive, exécutez :

npx lingo.dev@latest init

Il vous posera des questions sur votre projet, puis créera un fichier i18n.json à la racine de votre projet.

Le fichier devrait ressembler à ceci :

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Décomposons chaque élément de configuration :

• locale.source — La langue dans laquelle votre équipe écrit. Ce paramètre identifie les fichiers qui contiennent le contenu faisant autorité. Toute la localisation s'effectue de la source vers les cibles.

• locale.targets — Un tableau de codes de langue ISO 639-1 représentant vos marchés cibles. Chaque code correspond à un fichier distinct (ou une section dans un fichier, selon le format). Vous pouvez commencer avec une ou deux langues et en ajouter d'autres au fur et à mesure de votre expansion.

• buckets.json.include — Des modèles de type glob qui indiquent au CLI où trouver et créer des fichiers de localisation. Le jeton spécial [locale] s'étend à chaque code de langue. Avec le modèle locales/[locale].json, le CLI recherche locales/en.json comme source et génère locales/es.json et locales/ja.json comme cibles. Vous pouvez spécifier plusieurs modèles et même mélanger des formats dans une seule configuration.

Fonctionnalités avancées que vous découvrirez à mesure que votre projet se développe :

• Plusieurs buckets pour différents types de fichiers ou sections de votre application
• Modèles exclude pour ignorer certains fichiers
• lockedKeys pour empêcher la traduction de valeurs spécifiques

Créer le fichier source en anglais

Pour ce guide de démarrage rapide, nous allons créer un fichier de localisation :

mkdir -p locales
echo '{"greeting":"Hello, world!","button.submit":"Submit"}' > locales/en.json

Cela crée un répertoire locales et un fichier source en anglais avec deux clés de traduction. Les clés comme greeting fonctionnent pour les structures plates, tandis que les clés avec espace de noms comme button.submit aident à organiser les applications plus volumineuses.

Les objets imbriqués sont également pris en charge. Vous trouverez plus de détails sur les différents formats de fichiers dans le reste de la documentation.

Étape 2. Authentification

Le CLI Lingo.dev envoie votre contenu au moteur de traduction IA pour la localisation, nous devons donc d'abord nous authentifier.

Option 1. Accès direct à l'API LLM

Le CLI Lingo.dev vous aide à utiliser des modèles LLM comme OpenAI ou Anthropic pour la localisation et la traduction.

Cela signifie que vous êtes facturé par token traité, vous contrôlez la sélection du modèle, les prompts système et tous les paramètres du modèle.

Pour vous authentifier, créez un fichier .env dans la racine de votre projet avec votre clé API :

# si vous utilisez OpenAI

OPENAI_API_KEY=sk-...

# si vous utilisez Anthropic

ANTHROPIC_API_KEY=sk-...

Alternativement, au lieu d'utiliser .env, vous pouvez exporter la variable dans votre session shell actuelle :

export ANTHROPIC_API_KEY=sk-ant-...

Vous souhaitez ajouter la prise en charge d'un autre fournisseur ? Le CLI Lingo.dev est open source et accueille les contributions ! Forkez le dépôt et soumettez une pull request : github.com/lingodotdev/lingo.dev.

Option 2. Moteur Lingo.dev

Alternativement, vous pouvez créer un compte gratuit Lingo.dev Engine et l'utiliser comme moteur de traduction IA.

Il offre une sélection dynamique de modèles, un routage automatique vers différents modèles pour chaque paire de langues, des replis automatiques de modèles, une mémoire de traduction qui prend en compte les traductions antérieures, et la prise en charge de glossaires pour la terminologie spécifique au domaine de votre projet. Il existe des options gratuites et payantes, et le niveau gratuit Hobby devrait être suffisant pour ce tutoriel.

Pour vous authentifier, exécutez :

npx lingo.dev@latest login

Détail important. Si vous utilisez le navigateur Brave, ou si vos extensions de navigateur bloquent le flux d'authentification, vous pouvez vous authentifier manuellement en ajoutant une variable d'environnement LINGODOTDEV_API_TOKEN à votre fichier .env :

LINGODOTDEV_API_TOKEN=...

Vous trouverez le token dans les Paramètres du Projet Lingo.dev Engine.

Étape 3. Configurer le moteur de traduction IA

Maintenant que vous êtes authentifié, vous devez configurer le moteur de traduction IA à utiliser.

Option 1. Accès direct à l'API LLM

Pour utiliser OpenAI, mettez à jour votre configuration i18n.json pour utiliser le fournisseur openai :

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  },
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Act as a professional software localization expert. Translate each key from {source} to {target}. Preserve ICU message format placeholders like {name} and {{count}}. Maintain Markdown formatting including links and code blocks. Match the tone and formality of the source text. Technical terms that are typically untranslated in the industry should remain in English."
  }
}

Vous pouvez expérimenter avec différents prompts pour personnaliser le comportement de localisation, mais nous avons constaté que celui-ci constitue un bon point de départ !

La configuration du provider contrôle l'accès direct au LLM :

• id — Soit openai ou anthropic
• model — La version spécifique du modèle à utiliser. Exemples : gpt-4o-mini, gpt-4o (OpenAI), ou claude-3-haiku, claude-3-sonnet (Anthropic).
• prompt — Un prompt système qui guide le comportement de traduction. Les placeholders {source} et {target} sont remplacés par les codes de langue réels lors de l'exécution. Ce prompt est votre opportunité d'imposer une terminologie, un style et des règles spécifiques au domaine.

Option 2. Moteur Lingo.dev

Si vous utilisez le Moteur Lingo.dev comme moteur de traduction IA, vous pouvez omettre complètement le nœud provider.

Le moteur sélectionne automatiquement les modèles et les prompts en fonction des recherches de l'équipe Lingo.dev et des paramètres de votre moteur.

Votre configuration i18n.json :

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Remarque : Lorsque vous utilisez le Moteur Lingo.dev, omettez complètement le nœud provider. Le moteur sélectionne automatiquement les modèles et les prompts.

Étape 4. Traduire

Pour localiser votre application, exécutez :

npx lingo.dev@latest i18n

Le CLI créera les fichiers cibles et mettra à jour le fichier i18n.lock qui suit les empreintes digitales du contenu. Cela garantit des mises à jour incrémentales lors des exécutions ultérieures.

Vous avez maintenant localisé le contenu de votre application !

Prochaines étapes

Vous avez terminé le flux de travail de localisation principal. Votre dépôt contient désormais des fichiers localisés qui peuvent être validés, révisés et déployés comme n'importe quel autre artefact de code.

À partir d'ici, vous pouvez :

• Automatiser le flux de travail : Intégration CI/CD — Configurez l'intégration CI/CD pour localiser à chaque push, et valider automatiquement les modifications dans votre dépôt, via des pull requests ou des commits directs ;
• Comprendre les mécanismes internes : Comment ça fonctionne — Découvrez les algorithmes, les optimisations de performance et les décisions architecturales.