A API de localização da Lingo.dev traduz dados em formato chave-valor usando um engine de localização configurado. Com uma única chamada HTTP, suas strings entram e voltam traduzidas, com regras de glossário, voz da marca e seleção de modelo aplicadas automaticamente.
Quando usar a API#
Use a API de localização quando as traduções acontecerem em tempo de execução ou em um serviço de backend — não no momento do build.
| Caso de uso | Exemplo |
|---|---|
| Conteúdo dinâmico | Traduza descrições de cursos, títulos de aulas ou perguntas de questionários armazenados em um banco de dados |
| Conteúdo gerado por usuários | Traduza avaliações, comentários ou posts de fórum sob demanda |
| Respostas de API | Retorne conteúdo localizado do seu backend com base no idioma do usuário |
| Notificações | Traduza assuntos de e-mail, notificações push ou mensagens no app antes do envio |
Build-time vs runtime
Se o seu conteúdo está em arquivos estáticos (JSON, Markdown, .strings), a CLI ou a integração CI/CD é a opção mais adequada. A API foi projetada para localizar conteúdo no backend.
Pré-requisitos#
Crie um engine de localização
Toda chamada de API passa por um engine de localização — a configuração que define qual modelo de LLM, glossário, voz da marca e instruções serão aplicados. Crie um no dashboard da Lingo.dev.
Gere uma chave de API
As requisições da API são autenticadas com um cabeçalho X-API-Key. Gere uma chave na seção API Keys. As chaves são exibidas apenas uma vez no momento da criação — armazene a sua com segurança.
Localizando conteúdo#
Envie uma requisição POST para o endpoint localize com seu idioma de origem, idioma de destino e os dados em formato chave-valor. O esquema completo de requisição e resposta está documentado na referência da API.
Este exemplo traduz um parágrafo de um curso de JavaScript para espanhol:
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."
// }As chaves são preservadas: você envia intro e recebe intro de volta. O engine traduz apenas os valores.
Como estruturar as chaves#
O objeto data é plano — cada chave corresponde a uma única string. Estruture suas chaves de modo que elas tragam 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.",
};Chaves agrupadas semanticamente ajudam o engine de localização a gerar traduções mais coerentes. O engine interpreta todas as chaves em uma única requisição como contexto relacionado — variables.intro e variables.example são traduzidos com mais consistência quando enviados juntos do que separadamente.
Termos técnicos
Termos como "const" ou "let" são jargões de programação que não devem ser traduzidos. Use um glossário para marcar termos como não traduzíveis ou mapeá-los para equivalentes específicos do idioma. Se você usa um assistente de programação com IA como Claude Code ou Cursor, o Localization MCP pode ajudar a configurar regras de glossário como parte do seu workflow de desenvolvimento.
Localização ao salvar#
O padrão mais comum é traduzir o conteúdo quando ele é criado ou atualizado — não quando é lido. Assim, o conteúdo traduzido já está no banco de dados quando um usuário faz a solicitação.
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);
});Depois disso, ler conteúdo localizado passa a ser uma simples consulta ao banco de dados — sem necessidade de chamada de API no momento da leitura:
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);
});