Boas práticas

Estas práticas baseiam-se em padrões que produzem resultados fiáveis e económicos com o Compiler da Lingo.dev. 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

Controlo de versões#

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

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

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

Reveja os diffs das traduções#

Quando o CI faz commit de traduções atualizadas, reveja o diff de .lingo/metadata.json nos pull requests. Isto permite detetar problemas de tradução antes de chegarem à produção — tal como revê alterações ao código.

Organização do código#

Coloque o texto traduzível diretamente em JSX#

O Compiler analisa o JSX à procura de conteúdo traduzível. O texto guardado em variáveis JavaScript, constantes ou ficheiros externos não é detetado:

// 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 extensas#

Em projetos grandes, analisar todos os ficheiros aumenta o tempo de build. Ative useDirective: true e adicione 'use i18n' apenas aos ficheiros que contêm texto visível para o utilizador:

{
  useDirective: true,
}

'use i18n';

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

Mantenha o sourceRoot o mais restrito possível#

Defina sourceRoot como o diretório mais pequeno que contém os seus componentes traduzíveis. Um sourceRoot demasiado abrangente analisa ficheiros desnecessários:

Qualidade da tradução#

Use overrides manuais para termos da marca#

Nomes de marcas, nomes de produtos e texto jurídico 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 idiomas para otimizar custos#

Modelos diferentes têm pontos fortes e preços diferentes. Atribua os modelos mais dispendiosos aos idiomas que realmente precisam deles e use modelos mais económicos nos restantes 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 o motor da Lingo.dev para glossário e voz da marca#

Quando precisar de terminologia consistente em toda a aplicação, configure um motor de localização na Lingo.dev com um glossário e uma voz da marca. Estes são aplicados automaticamente a todos os pedidos de tradução.

Pluralização#

Desative a pluralização se não for necessária#

Se a sua aplicação não apresentar contagens numéricas juntamente com o texto, desative a pluralização para reduzir a complexidade do build:

{
  pluralization: { enabled: false },
}

Escreva naturalmente o texto dependente da contagem#

Quando a pluralização estiver ativada, escreva naturalmente o texto com variáveis numéricas. O Compiler trata 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 confirmar a cobertura total:

1. Ative dev.usePseudotranslator: true
2. Navegue por todas as páginas e componentes
3. Qualquer texto sem os marcadores [!!! ... !!!] não está a ser traduzido
4. Corrija problemas de colocação do texto (mova o texto para JSX, ajuste sourceRoot, 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 do lançamento:

{
  dev: { usePseudotranslator: false },
}

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

Próximos passos#