L’API de localisation de Lingo.dev traduit des données clé-valeur à l’aide d’un moteur de localisation configuré. Un seul appel HTTP suffit : vous envoyez vos chaînes, vous récupérez leurs traductions, avec les règles de glossaire, la voix de marque et le choix du modèle appliqués automatiquement.
Quand utiliser l’API#
Utilisez l’API de localisation lorsque la traduction s’effectue à l’exécution ou dans un service backend, et non au moment du build.
| Cas d’usage | Exemple |
|---|---|
| Contenu dynamique | Traduire des descriptions de cours, des titres de leçon ou des questions de quiz stockés dans une base de données |
| Contenu généré par les utilisateurs | Traduire à la demande des avis, des commentaires ou des messages de forum |
| Réponses d’API | Renvoyer du contenu localisé depuis votre backend en fonction de la langue de l’utilisateur |
| Notifications | Traduire des objets d’e-mail, des notifications push ou des messages in-app avant l’envoi |
Build-time vs runtime
Si votre contenu se trouve dans des fichiers statiques (JSON, Markdown, .strings), la CLI ou l’intégration CI/CD sera plus adaptée. L’API est conçue pour localiser du contenu côté backend.
Prérequis#
Créer un moteur de localisation
Chaque appel API passe par un moteur de localisation : c’est cette configuration qui détermine le modèle LLM, le glossaire, la voix de marque et les instructions à appliquer. Créez-en un dans le dashboard Lingo.dev.
Générer une clé API
Les requêtes API s’authentifient à l’aide d’un en-tête X-API-Key. Générez une clé dans la section Clés API. Les clés ne sont affichées qu’une seule fois lors de leur création : conservez la vôtre en lieu sûr.
Localiser du contenu#
Envoyez une requête POST au endpoint localize avec votre langue source, votre langue cible et vos données clé-valeur. Le schéma complet des requêtes et des réponses est documenté dans la référence API.
Cet exemple traduit un paragraphe d’un cours JavaScript vers l’espagnol :
const content = {
intro: "JavaScript is a programming language that powers the interactive elements of most websites. When you click a button, submit a form, or see content update without the page reloading, JavaScript is making that happen.",
};
const response = await fetch("https://api.lingo.dev/process/localize", {
method: "POST",
headers: {
"X-API-Key": "your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
engineId: "eng_abc123",
sourceLocale: "en",
targetLocale: "es",
data: content,
}),
});
const { data } = await response.json();
// {
// intro: "JavaScript es un lenguaje de programacion que impulsa los elementos interactivos de la mayoria de los sitios web. Cuando haces clic en un boton, envias un formulario o ves contenido actualizarse sin que la pagina se recargue, JavaScript lo esta haciendo posible."
// }Les clés sont conservées : vous envoyez intro et récupérez intro. Le moteur traduit uniquement les valeurs.
Structurer les clés#
L’objet data est plat : chaque clé correspond à une seule chaîne. Structurez vos clés de façon à véhiculer un contexte sémantique :
const content = {
"variables.intro": "Variables are containers for storing data values. In JavaScript, you declare them with let, const, or var.",
"variables.example": "Use const for values that never change, and let for values that do.",
"variables.exercise": "Declare a variable called age and assign it your age as a number.",
};Des clés regroupées par sens aident le moteur de localisation à produire des traductions plus cohérentes. Le moteur interprète toutes les clés d’une même requête comme un contexte partagé : variables.intro et variables.example seront traduits plus harmonieusement s’ils sont envoyés ensemble plutôt que séparément.
Termes techniques
Des termes comme "const" ou "let" relèvent du jargon de programmation et ne doivent pas être traduits. Utilisez un glossaire pour marquer certains termes comme non traduisibles, ou pour les associer à des équivalents propres à la langue. Si vous utilisez un assistant de code IA comme Claude Code ou Cursor, le Localization MCP peut vous aider à configurer les règles de glossaire dans votre workflow de développement.
Localiser à l’enregistrement#
Le schéma le plus courant consiste à traduire le contenu au moment de sa création ou de sa mise à jour, et non au moment de sa lecture. Ainsi, le contenu traduit est déjà présent dans la base de données lorsqu’un utilisateur le demande.
app.post("/api/lessons", async (req, res) => {
const lesson = await db.lessons.create(req.body);
const content = {
intro: lesson.intro,
example: lesson.example,
exercise: lesson.exercise,
};
const targetLocales = ["es", "fr", "de", "ja"];
const translations = await Promise.all(
targetLocales.map(async (targetLocale) => {
const response = await fetch("https://api.lingo.dev/process/localize", {
method: "POST",
headers: {
"X-API-Key": process.env.LINGODOTDEV_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
sourceLocale: "en",
targetLocale,
data: content,
}),
});
const { data } = await response.json();
return { locale: targetLocale, data };
})
);
await db.lessonTranslations.insertMany(
translations.map((t) => ({
lessonId: lesson.id,
locale: t.locale,
...t.data,
}))
);
res.json(lesson);
});La lecture du contenu localisé se résume alors à une simple requête en base de données : aucun appel API n’est nécessaire au moment de la lecture.
app.get("/api/lessons/:id", async (req, res) => {
const locale = req.query.locale || "en";
if (locale === "en") {
const lesson = await db.lessons.findById(req.params.id);
return res.json(lesson);
}
const translation = await db.lessonTranslations.findOne({
lessonId: req.params.id,
locale,
});
res.json(translation);
});