Referência de configuração

Alpha

O Lingo.dev Compiler está em alpha. Ainda é instável, não é recomendado para uso em produção e as APIs podem mudar entre releases.

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

Opções principais#

Opção	Tipo	Padrão	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 arquivos de cache.
`sourceLocale`	`string`	obrigatório	Código do idioma do seu conteúdo de origem (por exemplo, `"en"`).
`targetLocales`	`string[]`	obrigatório	Array com os códigos dos idiomas de destino (por exemplo, `["es", "de", "fr"]`).
`useDirective`	`boolean`	`false`	Quando `true`, apenas os arquivos com a diretiva `'use i18n'` são traduzidos. Quando `false`, todos os arquivos em `sourceRoot` são traduzidos.
`models`	`string \| object`	`"lingo.dev"`	Configuração do provedor de tradução. Uma string define o padrão para todos os pares de idioma. Um objeto mapeia pares de idioma para provedores específicos.
`prompt`	`string`	`undefined`	Prompt de sistema personalizado para o LLM de tradução. Compatível com os placeholders `{SOURCE_LOCALE}` e `{TARGET_LOCALE}`.
`buildMode`	`"translate" \| "cache-only"`	`"translate"`	Controla se o Compiler gera novas traduções ou usa apenas as traduções em cache.

Opções de desenvolvimento#

As opções dentro da chave dev controlam o comportamento durante o desenvolvimento:

Opção	Tipo	Padrão	Descrição
`dev.usePseudotranslator`	`boolean`	`false`	Gera traduções falsas instantâneas (por exemplo, `[!!! Welcome !!!]`) em vez de chamar um LLM. Não requer chave de API.
`dev.translationServerStartPort`	`number`	`60000`	Porta inicial do servidor de tradução local. O Compiler encontra automaticamente uma porta disponível no intervalo de 60000 a 60099.
`dev.translationServerUrl`	`string`	`undefined`	Substitui a URL do servidor de tradução. Útil em configurações personalizadas ou com servidores de tradução remotos.

Persistência de idioma#

As opções em localePersistence controlam como o idioma selecionado pelo usuário é armazenado e recuperado:

Opção	Tipo	Padrão	Descrição
`localePersistence.type`	`string`	`"cookie"`	Mecanismo de persistência. Atualmente, oferece suporte a `"cookie"`.
`localePersistence.config.name`	`string`	`"locale"`	Nome do cookie usado para armazenar o idioma.
`localePersistence.config.maxAge`	`number`	`31536000`	Tempo de vida máximo do cookie em segundos (o padrão é 1 ano).

Para uma lógica de persistência personalizada (localStorage, baseada em URL, headers), consulte Custom Locale Resolvers.

Pluralização#

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

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

Consulte Automatic Pluralization para entender em detalhes como funciona a detecção de plural.

Variáveis de ambiente#

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

Variável	Quando necessário	Descrição
`LINGO_BUILD_MODE`	Opcional	Substitui a opção de configuração `buildMode`. Defina como `"translate"` ou `"cache-only"`.
`LINGODOTDEV_API_KEY`	Ao usar modelos `"lingo.dev"`	Chave de API do engine de localização da Lingo.dev. Obtenha em `npx @lingo.dev/cli 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#

Provedores de tradução

Todos os provedores de LLM compatíveis e o mapeamento por par de idioma

Modos de build

Desenvolvimento, CI e workflows de produção

Custom Locale Resolvers

Implemente uma detecção de idioma personalizada

Boas práticas

Padrões recomendados para produção