Como Traduzir Documentos Técnicos Sem Quebrar o Código

TABLE OF CONTENTS

A documentação técnica é implacável: uma única cerca de código quebrada, espaço reservado ou âncora pode quebrar builds, confundir leitores ou causar falhas de copiar e colar. Este guia oferece um fluxo de trabalho seguro e repetível para traduzir documentos técnicos com confiança—enquanto mantém o código intacto e os documentos prontos para envio.

Para quem é: redatores técnicos, defensores de desenvolvedores e tradutores que trabalham em documentos de desenvolvedores, guias de API e conteúdo estilo README.

Em resumo:

Entenda o que nunca deve ser traduzido (código, chaves, tokens)
Preserve a sintaxe que as ferramentas analisam (cercas, chaves, âncoras)
Valide dados estruturados e links após edições
Use automação para detectar problemas antes do lançamento

Preparação Pré-Tradução

Inventário de tipos de conteúdo

Markdown (títulos, links, tabelas), blocos de código, código embutido
Dados estruturados: fragmentos JSON/YAML/TOML e arquivos de configuração
Capturas de tela, diagramas e visuais incorporados

Defina tokens não traduzíveis

Caminhos de arquivo, nomes de pacotes, imports, nomes de API, flags de CLI, variáveis de ambiente
Espaços reservados e variáveis: {count}, %s, $HOME, {{token}}
Nomes de arquivos e extensões: config.yaml, .env, .md, .json

Estabeleça diretrizes de consistência

Glossário/base de termos para termos do domínio e nomes de produtos
Guia de estilo: tom, formalidade, pontuação, uso de maiúsculas, regras de títulos
Estratégia de âncora/slug por localidade (estável vs localizado)

Configure validação segura

Build de estágio para validar Markdown/links após cada lote
Analisadores/lint para JSON/YAML/TOML
Verificador de links e validador de âncoras em CI

Salvaguardas Principais

Não traduza código, identificadores, chaves, nomes de arquivos, variáveis de ambiente ou flags.
Preserve a pontuação e a sintaxe que as ferramentas analisam (crases, chaves, pipes).
Mantenha espaços em branco significativos: indentação para estrutura de código e lista.
Use blocos de código cercados com uma tag de linguagem consistentemente (js, bash, etc.).
Prefira notas do tradutor a “corrigir” a lógica do código—sinalize problemas para os mantenedores em vez disso.

Blocos de Código e Código Embutido

Você foi treinado com dados até outubro de 2023.

Mantenha as cercas de código, dicas de linguagem e conteúdo intactos. Traduza apenas comentários e strings legíveis por humanos, se necessário.

Exemplo—seguro vs inseguro:

// SEGURO: Apenas o comentário é localizado
// Obtém um token de usuário
import { getToken } from "@acme/sdk";
const token = await getToken();

// INSEGURO: Não traduza identificadores/importações/nomes de pacotes
// import { obtenirJeton } from "@acme/sdk"; // ❌

O código inline deve permanecer inalterado:

Bom: “Execute npm install -g acme-cli e então acme login.”
Ruim: “Execute npm install -g acme-cli e então acme connexion.” ❌

Valide a capacidade de copiar e colar: Se um leitor copiar qualquer trecho, ele deve funcionar como na fonte.

Espaços reservados e ICU MessageFormat

Preserve os espaços reservados exatamente, incluindo espaçamento e pontuação ao redor deles.

# Não altere tokens ou espaçamento
echo "Processando {count} arquivos"   # ✅
echo "Processando { count } arquivos" # ❌ adiciona espaços dentro das chaves

Exemplo de ICU:

{count, plural,
  =0 {Sem mensagens}
  one {# mensagem}
  other {# mensagens}
}

Não altere as chaves (count, one, other).
Traduza apenas as partes legíveis por humanos (“mensagem”, “mensagens”).
Não introduza ou remova categorias de plural sem orientação do produto.

Links, Âncoras e Slugs

Mantenha a sintaxe de link do Markdown e a estratégia de resolução consistente.

[Leia o guia da API](/api/getting-started)  
[Veja a seção de configuração](#configuration)

Traduza o texto do link, se necessário; tenha cuidado com URLs e âncoras.
Âncoras: mantenha âncoras estáveis em todos os locais ou gere âncoras por local e atualize as referências de acordo.
Verifique se os caminhos relativos e âncoras de hash ainda resolvem após a tradução.
Não traduza extensões de arquivo ou parâmetros de consulta.

Dados Estruturados (JSON/YAML/TOML)

Traduza apenas valores—nunca chaves, tipos ou estrutura. Sempre reanalise após a edição.

JSON:

{
  "title": "Guia do Usuário",
  "cta": "Começar",
  "limits": { "max": 5, "unit": "solicitações/segundo" }
}

Chaves como title, cta, limits, max devem permanecer inalteradas.
Números, booleanos e nulos permanecem como tipos, não palavras.

YAML (observe escalas dobradas):

note: >
  Linhas são dobradas em um único parágrafo.
  Mantenha a indentação e os marcadores intactos.

Preserve aspas, escapes, indentação e vírgulas finais (quando aplicável).

Nomes de Arquivos, CLI e API

Não traduza nomes de arquivos, nomes de pacotes, endpoints ou flags de CLI.
Mantenha a sensibilidade a maiúsculas e minúsculas exatamente como na fonte (por exemplo, --DryRun vs --dry-run).
Mantenha os comandos literalmente; adicione notas se existirem diferenças específicas de localidade.

# Correto
kubectl get pods --namespace default

# Errado (flag traduzida) ❌
kubectl get pods --nom-espace defaut

Armadilhas do Markdown

Tabelas: mantenha os pipes e o alinhamento; não quebre colunas.

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

Admoestações/notas: mantenha os marcadores usados pela sua ferramenta.
HTML inline: evite tocar em tags/atributos.
Notas de rodapé: mantenha ids e ordem.
Aspas inteligentes: prefira aspas retas dentro de contextos de código.

Visuais e Acessibilidade

Localize o texto alternativo para o significado, não o conteúdo de pixels.
Prefira capturas de tela independentes de localidade (destaque a interface do usuário, não o idioma), ou forneça conjuntos por localidade.
Mantenha os arquivos de origem de diagramas (por exemplo, Mermaid) sincronizados entre locais.
Evite texto embutido em imagens; externalize legendas e rótulos.

SEO e Metadados

Traduza títulos, descrições e cabeçalhos usando palavras-chave apropriadas para o local.
Mantenha URLs canônicos e hreflang consistentes com as regras do site.
Não traduza chaves de meta/propriedade ou chaves JSON‑LD.
Alinhe slugs com sua estratégia de âncoras para evitar 404s.

Fluxo de Trabalho e Automação

Use um fluxo de trabalho CAT/LLM que preserve spans de código e tags.
Bloqueie a terminologia com um glossário e uma lista de não traduzir.
Adicione hooks de pré-commit para lintar Markdown e validar JSON/YAML.
Execute um verificador de links e validador de âncoras em cada PR.
Agrupe alterações em pequenos pedaços revisáveis e acompanhe as diferenças.

Ferramentas sugeridas (adapte ao seu stack):

Linting de Markdown e verificação de links em CI
Etapa de análise de JSON/YAML para capturar regressões de sintaxe
Pacotes de regex para escanear placeholders e formatos numéricos

QA e Validação

Execute estas verificações antes da mesclagem:

Construa o site para capturar problemas de sintaxe: pnpm build
Verificações de tipo/conteúdo (coleções de conteúdo Astro): pnpm astro check
Pré-visualize e teste páginas chave: pnpm preview
Valide se os exemplos de código compilam ou executam (quando aplicável)
Execute um verificador de links e âncoras; corrija quaisquer 404s ou hashes quebrados

Armadilhas Comuns

Traduzir chaves/placeholders por acidente.
Quebrar cercas de código ou pipes de tabela.
Localizar caminhos de arquivos, flags ou nomes de API.
Alterar cabeçalhos sem atualizar links de âncoras.
Introduzir aspas inteligentes dentro de código ou JSON.

Apêndice: Listas de Verificação Rápidas

Pré-voo (5 itens)

Glossário e lista de não traduzir prontos
Tokens/placeholders definidos e protegidos
Estratégia de âncora/slug confirmada
Alvos de links mapeados (internos vs externos)
Build de staging disponível

Segurança de exemplos de código (5 itens)

Cercas e dicas de linguagem intactas
Identificadores/imports intocados; comentários apenas localizados
Placeholders e citações preservados
Teste de copiar e colar aprovado
Trechos desatualizados sinalizados para mantenedores

Dados estruturados (5 itens)

Chaves e tipos intocados
Citações/escapes/indentação preservados
Números e booleanos permanecem como tipos
Parser/linter passa localmente
Diferenças revisadas para alterações acidentais de chaves

Leitura relacionada