La API de localización de Lingo.dev traduce datos de clave-valor mediante un motor de localización configurado. Una llamada HTTP: envías tus cadenas y recibes las cadenas traducidas, con las reglas del glosario, la voz de marca y la selección del modelo aplicadas automáticamente.
Cuándo usar la API#
Usa la API de localización cuando las traducciones se hagan en tiempo de ejecución o en un servicio de backend, no en tiempo de compilación.
| Caso de uso | Ejemplo |
|---|---|
| Contenido dinámico | Traduce descripciones de cursos, títulos de lecciones o preguntas de cuestionarios almacenados en una base de datos |
| Contenido generado por usuarios | Traduce reseñas, comentarios o publicaciones en foros bajo demanda |
| Respuestas de API | Devuelve contenido localizado desde tu backend según el idioma del usuario |
| Notificaciones | Traduce asuntos de correo electrónico, notificaciones push o mensajes dentro de la app antes de enviarlos |
Compilación vs. tiempo de ejecución
Si tu contenido está en archivos estáticos (JSON, Markdown, .strings), la CLI o la integración con CI/CD encajan mejor. La API está pensada para localizar contenido en el backend.
Requisitos previos#
Crea un motor de localización
Todas las llamadas a la API pasan por un motor de localización: la configuración que determina qué modelo LLM, glosario, voz de marca e instrucciones se aplican. Crea uno en el panel de Lingo.dev.
Genera una clave de API
Las solicitudes a la API se autentican con una cabecera X-API-Key. Genera una clave en la sección API Keys. Las claves solo se muestran una vez al crearlas, así que guarda la tuya de forma segura.
Localizar contenido#
Envía una solicitud POST al endpoint localize con tu idioma de origen, idioma de destino y los datos de clave-valor. El esquema completo de solicitud y respuesta está documentado en la referencia de la API.
Este ejemplo traduce un párrafo de un curso de JavaScript al español:
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."
// }Las claves se conservan: envías intro y recibes intro. El motor traduce solo los valores.
Cómo estructurar las claves#
El objeto data es plano: cada clave se corresponde con una única cadena. Estructura las claves para que aporten contexto semántico:
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.",
};Agrupar las claves por significado ayuda al motor de localización a generar traducciones más coherentes. El motor interpreta todas las claves de una misma solicitud como contexto relacionado: variables.intro y variables.example se traducen de forma más consistente cuando se envían juntas que por separado.
Términos técnicos
Términos como "const" o "let" son jerga de programación y no deben traducirse. Usa un glosario para marcarlos como no traducibles o asignarlos a equivalentes específicos del idioma. Si usas un asistente de programación con IA como Claude Code o Cursor, Localization MCP puede ayudarte a configurar reglas de glosario como parte de tu flujo de trabajo de desarrollo.
Localizar al guardar#
Lo habitual es traducir el contenido cuando se crea o se actualiza, no cuando se consulta. Así, el contenido traducido ya está en la base de datos cuando un usuario lo solicita.
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);
});A partir de ahí, leer contenido localizado se reduce a una simple consulta a la base de datos, sin necesidad de llamar a la API en el momento de la lectura:
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);
});