Como Localizar um App Gerado por IA

Este guia explica como internacionalizar e depois localizar um app gerado por IA: chaves, arquivos de locale, extração, glossários e automação que resiste a mudanças rápidas na UI. O globalize.now é uma infraestrutura de localização com IA que mantém esses catálogos alinhados com o Git em cada push, então você configura uma vez, sincroniza automaticamente a cada push e evita idas e vindas manuais com arquivos. Para entender por que bases de código feitas primeiro com IA costumam pular a camada de i18n, leia O código de IA quebrou a localização — e ninguém corrigiu isso. Para contexto sobre as eras de ferramentas do setor, veja 3 Estágios do Desenvolvimento de Localização (E Por Que a IA Muda Tudo). Para a ordem certa de fornecedores quando os repositórios ainda estão desorganizados, leia globalize.now vs Lokalise vs Crowdin e o passo a passo prático em Como Globalizar Seu App com o globalize.now.

---

O que realmente significa “localizar um app gerado por IA”?

Localização (l10n) é o que os usuários veem: idioma correto, plurais, datas, moeda e layout para o locale deles.

Internacionalização (i18n) é o que os engenheiros fazem primeiro: tornar o texto visível ao usuário endereçável, repetível e seguro para traduzir em escala.

A maioria dos bloqueios do tipo “ainda não conseguimos localizar” são, na verdade, bloqueios de i18n. Corrija a arquitetura uma vez, e a localização passa a ser um problema operacional em vez de um projeto de arqueologia.

---

O que deve estar em um checklist de arquitetura de i18n antes de escolher as ferramentas?

Antes de escolher um software de coordenação de tradução ou um fornecedor de tradução, confirme que esses blocos existem — ou planeje introduzi-los nesta ordem:

• Biblioteca de i18n em tempo de execução apropriada para sua stack (React, Next.js, Rails, etc.), com um único padrão suportado para strings de UI.
• Chaves de tradução estáveis (com namespace, hierárquicas) em vez de frases em inglês como IDs.
• Arquivos de recursos de locale (JSON, PO, YAML) versionados no repositório ou gerados no CI.
• Plurais e variáveis no estilo ICU para frases dinâmicas como "{count} items", para que os tradutores possam reordenar a gramática com segurança.
• Um pipeline de extração de strings para que a UI nova não ignore o catálogo silenciosamente.

---

Como extrair strings sem perder velocidade?

Repositórios gerados por IA tendem a repetir os mesmos rótulos (“Salvar”, “Cancelar”, “Saiba mais”) em dezenas de arquivos. Sua etapa de extração deve:

1. Detectar literais visíveis ao usuário em componentes, rotas e primitivas de UI compartilhadas — ignorando strings técnicas (classes CSS, IDs de analytics, URLs, a menos que sejam voltadas ao usuário).
2. Normalizar duplicatas em uma única chave com referências, para que os tradutores vejam uma única unidade de sentido.
3. Gerar um locale de origem (geralmente inglês) como o valor canônico de cada nova chave.
4. Reescrever os pontos de chamada para usar a API de i18n definida pela sua equipe — de forma mecânica, para que o diff permaneça revisável.

Um exemplo mínimo de antes/depois em código estilo React fica assim:

<button>Submit order</button>

Depois da extração e criação de chaves:

<button>{t("checkout.submit_order")}</button>

// locales/en.json
{
  "checkout.submit_order": "Submit order"
}

---

Por que glossários e guias de estilo importam antes de escalar idiomas?

A tradução automática é rápida. Também é fácil fazer com que cada tela pareça um produto diferente se você não definir restrições. Antes de escalar para muitos idiomas, defina por escrito:

• Termos de marca que não devem ser traduzidos (nome do produto, nomes de funcionalidades).
• Traduções preferidas para palavras de alto risco (“contato”, “teste grátis”, “cobrança”, “workspace”).
• Tom: formal versus conversacional, e segunda pessoa versus neutro.

Alimente esse glossário na sua stack de coordenação ou no perfil de MT, para que os rascunhos automatizados permaneçam alinhados com as decisões que sua equipe já tomou.

---

Como as verificações automatizadas devem ancorar o ciclo de QA de tradução?

Depois que as chaves entram nos arquivos de locale, o ciclo moderno é: rascunho de MT → verificações do linter (tamanho, placeholders, termos proibidos) → verificações de regressão automatizadas nas superfícies de maior impacto → lançamento → medição. A automação economiza tempo; o linter evita que você lance placeholders quebrados.

Ferramentas no estilo CLI podem dar um retorno rápido sobre quanto trabalho ainda resta no repositório, algo como:

✔ Scanned 312 files
✔ Found 1,284 user-visible literals
✔ Proposed 920 translation keys (364 duplicates merged)
✔ Wrote locales/en.json

Next: sync translation-ready keys to your coordination tool or run an MT batch with glossary v1

---

Quais prompts de agente mantêm as refatorações de localização revisáveis?

Esses prompts partem do princípio de que você está trabalhando em um repositório com testes e revisão de código. Eles foram escritos para gerar diffs em que você pode confiar — não refatorações amplas e silenciosas.

Como inventariar as strings de UI antes de refatorar?

You are analyzing a TypeScript React codebase for localization readiness.

Task: List every pattern where user-visible English might appear (JSX text, string props that render to the DOM, template literals interpolated into UI, aria-label/title/placeholder, toasts, empty states). Exclude className values, internal IDs, and URLs that are not shown to users.

Output: a table with columns: file path, line range, example string, recommended next step (extract key / ignore / needs product decision).

Como introduzir com segurança uma API t() mínima e tipada?

Add a minimal i18n helper used across the app: a typed t(key, vars?) function backed by JSON locale files in /locales. Do not translate yet—only wire English as the source locale.

Constraints:
- Keys use dot namespaces: "section.component.purpose"
- Support ICU-style pluralization for keys that need counts
- Add a dev-only warning when t() is called with a missing key

Show the file tree you created and example usage in two existing components.

Como extrair literais mecanicamente em chaves com namespace?

Refactor the following files to replace user-visible string literals with t("…") keys.

Rules:
- Prefer stable semantic keys, not English sentences as keys
- Deduplicate identical UI strings to one key
- Keep string interpolation correct using ICU message patterns
- Do not change layout/styling except where required by the refactor

After edits, print a JSON object mapping each new key to its English source string for translators.

Como redigir um CSV de glossário em que os tradutores possam confiar?

From locales/en.json and the product marketing pages in this repo, propose a glossary CSV with columns: term_en, part_of_speech, definition_for_translators, do_not_translate (true/false), allowed_synonyms, notes_for_de.

Flag terms that are legally sensitive (pricing, trials, refunds) and terms that are ambiguous in software ("session", "organization", "member").

Qual barreira de CI impede que novo inglês fixo entre no código?

Add a CI script that fails if new user-visible English literals appear in JSX outside of tests/fixtures.

Implementation guidance:
- Use the repo's existing package manager and test runner
- Provide a small allowlist file for exceptions (brand strings, intentional English)
- Print actionable file/line references on failure

Include README notes for how engineers should add exceptions responsibly.

---

Ainda é preciso colar esses prompts manualmente?

Cada vez menos. Quando este guia foi escrito originalmente, copiar e colar prompts no seu agente era a forma prática de executar o ciclo. Desde então, as ferramentas migraram para dentro do próprio agente: agentes de código agora podem chamar a localização diretamente por um servidor MCP, então a extração, a criação de chaves e a sincronização de tradução passam a ser chamadas de ferramentas feitas pelo agente, em vez de prompts que você cola. Veja Apresentando o MCP do globalize.now para a configuração, e Localização está se tornando uma skill de agente, não um SDK para entender por que essa mudança é arquiteturalmente importante.

Os prompts acima continuam úteis como checklists de revisão — eles descrevem o que uma boa refatoração de i18n conduzida por agente precisa fazer, seja um humano colando-os ou uma skill de agente codificando-os. Avalie qualquer refatoração automatizada pelo mesmo padrão: diffs revisáveis, chaves estáveis, interpolação segura para ICU e uma barreira de CI que impeça regressões.

---

Qual restrição de longo prazo você deve lembrar ao localizar produtos construídos com IA?

Localização não é um único sprint — é um contrato com o seu eu futuro. Se você investir uma vez em chaves, catálogos e automação, cada nova tela gerada por IA fica mais barata de lançar para o mundo todo.