Boas práticas

Estas práticas se baseiam em padrões que geram resultados confiáveis e com bom custo-benefício com o Compiler da Lingo.dev. Elas abrangem o pipeline de build, a organização do código, a qualidade da tradução e os testes.

Pipeline de build#

Use a estratégia de três modos#

{
  buildMode: "translate",
  dev: { usePseudotranslator: true },
}

LINGO_BUILD_MODE=translate npm run build

LINGO_BUILD_MODE=cache-only npm run build

Controle de versão#

Faça commit de .lingo/ no repositório#

O arquivo .lingo/metadata.json é a fonte da verdade de todas as traduções em cache. Os builds de produção no modo cache-only dependem dele.

# .gitignore - do NOT ignore .lingo/
node_modules/
dist/
.env

Revise os diffs de tradução#

Quando o CI fizer commit das traduções atualizadas, revise o diff de .lingo/metadata.json nos pull requests. Assim, você consegue identificar problemas de tradução antes que eles cheguem à produção — como acontece na revisão de alterações de código.

Organização do código#

Coloque o texto traduzível direto no JSX#

O Compiler analisa o JSX em busca de conteúdo traduzível. Texto armazenado em variáveis JavaScript, constantes ou arquivos externos não é detectado:

// Good - compiler detects this text
export function Header() {
  return <h1>Welcome to our app</h1>;
}

// Bad - compiler cannot detect text in a variable
const title = "Welcome to our app";
export function Header() {
  return <h1>{title}</h1>;
}

Use useDirective em bases de código grandes#

Em projetos grandes, analisar todos os arquivos aumenta o tempo de build. Ative useDirective: true e adicione 'use i18n' apenas aos arquivos que contêm texto exibido ao usuário:

{
  useDirective: true,
}

'use i18n';

// Only this file is scanned for translations
export function PublicPage() {
  return <h1>Welcome</h1>;
}

Mantenha o sourceRoot enxuto#

Defina sourceRoot como o menor diretório que contém seus componentes traduzíveis. Um sourceRoot amplo demais faz a análise de arquivos desnecessários:

Qualidade da tradução#

Use overrides manuais para termos da marca#

Nomes de marca, nomes de produto e textos legais devem usar manual overrides, em vez de depender da tradução por IA:

<h1 data-lingo-override={{ es: "Motor de Localizacion", de: "Lokalisierungs-Engine" }}>
  Localization Engine
</h1>

Use o mapeamento de pares de idioma para otimizar custos#

Modelos diferentes têm pontos fortes e faixas de preço diferentes. Mapeie os modelos mais caros para os idiomas que realmente precisam deles e use modelos com melhor custo-benefício nos demais casos:

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",      // Fast, cost-effective default
    "*:ja": "anthropic:claude-3-5-sonnet",       // Higher quality for Japanese
    "*:zh-Hans": "anthropic:claude-3-5-sonnet",  // Higher quality for Chinese
  },
}

Use a engine da Lingo.dev para glossário e voz da marca#

Quando você precisar de terminologia consistente em todo o app, configure uma engine de localização na Lingo.dev com um glossário e uma voz da marca. Eles são aplicados automaticamente a cada solicitação de tradução.

Pluralização#

Desative a pluralização se não precisar dela#

Se o seu app não exibe contagens numéricas junto com o texto, desative a pluralização para reduzir a complexidade do build:

{
  pluralization: { enabled: false },
}

Escreva textos dependentes de contagem de forma natural#

Quando a pluralização estiver ativada, escreva naturalmente o texto com variáveis numéricas. O Compiler cuida da conversão para ICU MessageFormat:

// Good - the compiler detects and pluralizes this
<p>You have {count} items in your cart</p>

// Also good - works with any numeric expression
<p>{unreadCount} unread messages</p>

Testes#

Teste primeiro com o pseudotradutor#

Antes de gerar traduções reais, execute com o pseudotradutor para verificar a cobertura completa:

1. Ative dev.usePseudotranslator: true
2. Navegue por todas as páginas e componentes
3. Qualquer texto sem os marcadores [!!! ... !!!] não está sendo traduzido
4. Corrija problemas de posicionamento do texto (mova o texto para o JSX, ajuste sourceRoot e adicione diretivas 'use i18n')

Teste com traduções reais antes do lançamento#

Desative o pseudotradutor e gere traduções reais para pelo menos um idioma de destino antes de lançar:

{
  dev: { usePseudotranslator: false },
}

Verifique overflow de layout, truncamento de texto e problemas com texto bidirecional que as pseudotraduções não conseguem revelar.

Próximos passos#