A API de localização da Lingo.dev traduz dados em pares chave-valor através de um motor de localização configurado. Basta uma chamada HTTP — as suas strings entram e saem já traduzidas, com regras de glossário, voz da marca e seleção de modelo aplicadas automaticamente.
Quando utilizar a API#
Utilize a API de localização quando as traduções acontecem em tempo de execução ou num serviço de backend — não durante a build.
| Caso de uso | Exemplo |
|---|---|
| Conteúdo dinâmico | Traduzir descrições de cursos, títulos de aulas ou perguntas de questionários armazenadas numa base de dados |
| Conteúdo gerado pelo utilizador | Traduzir avaliações, comentários ou publicações em fóruns a pedido |
| Respostas da API | Devolver conteúdo localizado a partir do seu backend com base no idioma do utilizador |
| Notificações | Traduzir assuntos de email, notificações push ou mensagens na app antes do envio |
Build-time vs runtime
Se o seu conteúdo estiver em ficheiros estáticos (JSON, Markdown, .strings), a CLI ou a integração CI/CD são opções mais adequadas. A API foi pensada para localizar conteúdo no backend.
Pré-requisitos#
Criar um motor de localização
Cada chamada à API passa por um motor de localização — a configuração que determina que modelo LLM, glossário, voz da marca e instruções se aplicam. Crie um no dashboard da Lingo.dev.
Gerar uma chave de API
Os pedidos à API autenticam-se com um cabeçalho X-API-Key. Gere uma chave na secção API Keys. As chaves são mostradas apenas uma vez, no momento da criação — guarde a sua em segurança.
Localizar conteúdo#
Envie um pedido POST para o endpoint localize com o seu idioma de origem, idioma de destino e os seus dados em pares chave-valor. O esquema completo de pedido/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: envia intro e recebe intro. O motor traduz apenas os valores.
Estruturar chaves#
O objeto data é plano — cada chave corresponde a uma única string. Estruture as suas chaves de forma a transmitirem 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 motor de localização a produzir traduções mais coerentes. O motor vê todas as chaves num único pedido como contexto relacionado — variables.intro e variables.example são traduzidos de forma mais consistente quando enviados em conjunto do que em separado.
Termos técnicos
Termos como "const" ou "let" são jargão de programação e não devem ser traduzidos. Utilize um glossário para marcar termos como não traduzíveis, ou mapeá-los para equivalentes específicos do idioma. Se utilizar um assistente de programação com IA, como o Claude Code ou o Cursor, o Localization MCP pode ajudar a configurar regras de glossário como parte do seu workflow de desenvolvimento.
Localizar ao guardar#
O padrão mais comum é traduzir conteúdo quando é criado ou atualizado — não quando é lido. Assim, o conteúdo traduzido já está na base de dados quando um utilizador o pede.
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 leitura de conteúdo localizado passa então a ser uma simples consulta à base de dados — sem necessidade de fazer uma chamada à 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);
});