Referência de Configuração

Alfa

O Compiler da Lingo.dev está em alfa. É instável, não é recomendado para utilização em produção e as APIs podem mudar entre versões.

O objeto de configuração do Compiler da Lingo.dev controla a forma como a sua aplicação React é traduzida durante o build. Esta página documenta todas as opções disponíveis, com tipos, valores predefinidos e exemplos de utilização.

Opções principais#

Opção	Tipo	Predefinido	Descrição
`sourceRoot`	`string`	`"src"`	Diretório que contém os componentes traduzíveis. Relativo à raiz do projeto.
`lingoDir`	`string`	`".lingo"`	Diretório para metadados de tradução e ficheiros de cache.
`sourceLocale`	`string`	obrigatório	Código do idioma do seu conteúdo de origem (por exemplo, `"en"`).
`targetLocales`	`string[]`	obrigatório	Array de códigos dos idiomas de destino (por exemplo, `["es", "de", "fr"]`).
`useDirective`	`boolean`	`false`	Quando `true`, só são traduzidos os ficheiros com a diretiva `'use i18n'`. Quando `false`, são traduzidos todos os ficheiros em `sourceRoot`.
`models`	`string \| object`	`"lingo.dev"`	Configuração do fornecedor de tradução. Uma string define o valor predefinido para todos os pares de idiomas. Um objeto mapeia pares de idiomas para fornecedores específicos.
`prompt`	`string`	`undefined`	Prompt de sistema personalizado para o LLM de tradução. Suporta os marcadores `{SOURCE_LOCALE}` e `{TARGET_LOCALE}`.
`buildMode`	`"translate" \| "cache-only"`	`"translate"`	Controla se o Compiler gera novas traduções ou se usa apenas traduções em cache.

Opções de desenvolvimento#

As opções na chave dev controlam o comportamento em desenvolvimento:

Opção	Tipo	Predefinido	Descrição
`dev.usePseudotranslator`	`boolean`	`false`	Gera instantaneamente traduções fictícias (por exemplo, `[!!! Welcome !!!]`) em vez de chamar um LLM. Não é necessária nenhuma chave de API.
`dev.translationServerStartPort`	`number`	`60000`	Porta inicial para o servidor local de tradução. O Compiler encontra automaticamente uma porta disponível no intervalo 60000-60099.
`dev.translationServerUrl`	`string`	`undefined`	Substitui o URL do servidor de tradução. Útil para configurações personalizadas ou servidores de tradução remotos.

Persistência do idioma#

As opções em localePersistence controlam a forma como o idioma selecionado pelo utilizador é armazenado e recuperado:

Opção	Tipo	Predefinido	Descrição
`localePersistence.type`	`string`	`"cookie"`	Mecanismo de persistência. Atualmente, suporta `"cookie"`.
`localePersistence.config.name`	`string`	`"locale"`	Nome do cookie usado para guardar o idioma.
`localePersistence.config.maxAge`	`number`	`31536000`	Tempo de vida máximo do cookie, em segundos (o valor predefinido é 1 ano).

Para lógica de persistência personalizada (localStorage, baseada em URL, headers), consulte Resolvedores de Idioma Personalizados.

Pluralização#

As opções em pluralization controlam a deteção e a geração automáticas de formas no plural:

Opção	Tipo	Predefinido	Descrição
`pluralization.enabled`	`boolean`	`true`	Ativa ou desativa a deteção automática de pluralização.
`pluralization.model`	`string`	`"groq:llama-3.1-8b-instant"`	Modelo LLM usado para detetar formas no plural no texto de origem. Recomenda-se um modelo mais pequeno e mais rápido, uma vez que a deteção é uma tarefa mais simples do que a tradução.

Consulte Pluralização Automática para saber mais sobre o funcionamento da deteção de plural.

Variáveis de ambiente#

As variáveis de ambiente substituem ou complementam a configuração:

Variável	Quando é obrigatória	Descrição
`LINGO_BUILD_MODE`	Opcional	Substitui a opção de configuração `buildMode`. Defina-a como `"translate"` ou `"cache-only"`.
`LINGODOTDEV_API_KEY`	Ao usar modelos `"lingo.dev"`	Chave de API para o motor de localização da Lingo.dev. Obtenha-a em `npx lingo.dev@latest login`.
`OPENAI_API_KEY`	Ao usar modelos `"openai:*"`	Chave de API da OpenAI.
`ANTHROPIC_API_KEY`	Ao usar modelos `"anthropic:*"`	Chave de API da Anthropic.
`GOOGLE_API_KEY`	Ao usar modelos `"google:*"`	Chave de API do Google AI.
`GROQ_API_KEY`	Ao usar modelos `"groq:*"`	Chave de API da Groq.
`MISTRAL_API_KEY`	Ao usar modelos `"mistral:*"`	Chave de API da Mistral.
`OPENROUTER_API_KEY`	Ao usar modelos `"openrouter:*"`	Chave de API da OpenRouter.

Exemplo completo#

// next.config.ts
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    lingoDir: ".lingo",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    useDirective: false,
    models: {
      "*:*": "lingo.dev",
      "*:ja": "anthropic:claude-3-5-sonnet",
    },
    prompt: "Translate UI text from {SOURCE_LOCALE} to {TARGET_LOCALE}. Keep it concise.",
    buildMode: "translate",
    dev: {
      usePseudotranslator: true,
      translationServerStartPort: 60000,
    },
    localePersistence: {
      type: "cookie",
      config: {
        name: "locale",
        maxAge: 31536000,
      },
    },
    pluralization: {
      enabled: true,
      model: "groq:llama-3.1-8b-instant",
    },
  });
}

Próximos passos#

Fornecedores de Tradução

Todos os fornecedores de LLM suportados e o mapeamento por pares de idiomas

Modos de Build

Workflows de desenvolvimento, CI e produção

Resolvedores de Idioma Personalizados

Implemente a deteção personalizada de idioma

Boas Práticas

Padrões recomendados para produção