Estrutura do Projeto

O Compiler da Lingo.dev cria e mantém um diretório .lingo/ na raiz do projeto para armazenar metadados de tradução e cache. Entender essa estrutura ajuda você a gerenciar traduções no controle de versão, depurar traduções ausentes e otimizar o desempenho do build.

O diretório .lingo/#

O Compiler cria esse diretório automaticamente no primeiro build. Ele reúne todos os metadados de tradução usados no pipeline de build:

.lingo/
  metadata.json              # Translation cache and content hashes
  locale-resolver.server.ts  # Optional: custom server-side locale resolver
  locale-resolver.client.ts  # Optional: custom client-side locale resolver

metadata.json#

Este é o arquivo principal no diretório .lingo/. Ele armazena:

• Hashes de conteúdo — identificadores estáveis baseados em hash para cada string traduzível
• Traduções em cache — traduções geradas para cada par de idioma
• Snapshots do texto-fonte — o texto-fonte no momento da tradução, usado para detectar alterações

O Compiler lê esse arquivo no início de cada build. Strings com hashes correspondentes reutilizam traduções em cache. Strings com hashes alterados ou ausentes são enviadas ao provedor de tradução configurado.

Cuidados com o .gitignore#

Não adicione .lingo/ ao .gitignore. Esse diretório deve ser versionado. Exemplo de .gitignore típico para um projeto que usa o Compiler:

# Do NOT ignore .lingo/ - it contains translation cache
node_modules/
dist/
.env

sourceRoot#

A opção sourceRoot define qual diretório o Compiler vai varrer em busca de componentes React traduzíveis:

{
  sourceRoot: "./app",  // Next.js App Router
  // or
  sourceRoot: "src",    // Vite + React
}

O Compiler faz uma varredura recursiva de todos os arquivos .tsx, .ts, .jsx e .js dentro de sourceRoot em busca de conteúdo JSX traduzível. Arquivos fora desse diretório não são processados.

Modo opt-in com 'use i18n'#

Por padrão, o Compiler traduz todo o texto JSX em sourceRoot. Para mudar para o modo opt-in, defina useDirective: true:

{
  useDirective: true,
}

No modo opt-in, apenas arquivos que começam com a diretiva 'use i18n' são processados:

'use i18n';

export function Welcome() {
  return <h1>Welcome to our app</h1>;
  // This text IS translated
}

Arquivos sem a diretiva são ignorados:

export function InternalAdmin() {
  return <h1>Admin Dashboard</h1>;
  // This text is NOT translated
}

Quando usar o modo opt-in#

lingoDir#

A opção lingoDir altera o local do diretório de metadados:

{
  lingoDir: ".lingo",  // Default
  // or
  lingoDir: ".translations",  // Custom location
}

Isso é útil se .lingo/ entrar em conflito com um diretório já existente no projeto.

Próximos passos#