Estrutura do Projeto

O Compiler da Lingo.dev cria e mantém um diretório .lingo/ na raiz do projeto, onde armazena metadados de tradução e cache. Perceber esta estrutura ajuda-o a gerir traduções no controlo de versões, diagnosticar traduções em falta e otimizar o desempenho da build.

O diretório .lingo/#

O Compiler cria este diretório automaticamente na primeira build. Contém todos os metadados de tradução usados pelo 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 ficheiro principal no diretório .lingo/. 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 idiomas
• Snapshots do texto de origem — o texto de origem no momento da tradução, usado para detetar alterações

O Compiler lê este ficheiro no início de cada build. As strings com hashes correspondentes reutilizam as traduções em cache. As strings com hashes alterados ou em falta são enviadas para o fornecedor de tradução configurado.

Considerações sobre o .gitignore#

Não adicione .lingo/ ao .gitignore. O diretório deve ficar sob controlo de versões. Exemplo de um .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 que diretório o Compiler analisa à procura de componentes React traduzíveis:

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

O Compiler analisa recursivamente todos os ficheiros .tsx, .ts, .jsx e .js dentro de sourceRoot à procura de conteúdo JSX traduzível. Os ficheiros fora deste diretório não são processados.

Modo opt-in com "use i18n"#

Por predefiniçã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, só são processados os ficheiros que começam com a diretiva 'use i18n':

'use i18n';

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

Os ficheiros 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 a localização do diretório de metadados:

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

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

Próximos passos#