Localize conteúdo estático
Mapeie documentos e catálogos traduzidos para os arquivos que seu site ou renderizador consome. Depois, verifique a estrutura, os links e o resultado entregue.
A árvore de arquivos-fonte do seu site já conecta artigos a rotas, metadados, navegação e um renderizador. Adicione os arquivos traduzidos onde esse sistema consiga carregá-los. O primeiro resultado útil é uma página completa no idioma de destino, na rota prevista, com links funcionando e os mesmos exemplos de código do original.
Catalogue os arquivos de acordo com o sistema que os consome #
Separe documentos longos de catálogos estruturados e recursos especializados. Markdown, MDX e Markdoc precisam de um renderizador e de um esquema. Catálogos JSON, YAML, TypeScript e PHP precisam de um carregador. PO e XLIFF se conectam aos seus próprios sistemas de mensagens. SRT faz parte de um workflow de mídia com marcação de tempo.
Escolha um arquivo-fonte representativo de cada grupo e identifique o caminho de saída e o carregador que consumirá o resultado. Mantenha os arquivos de destino gerados fora dos padrões de seleção dos arquivos-fonte. Preserve IDs de documentos, URLs, exemplos de código, chaves de catálogo e atributos de componentes cujos valores controlam o comportamento.
Use Formatos para selecionar o processador adequado. YAML comum é diferente de YAML com idioma na raiz e de YAML OpenAPI. .xml não identifica automaticamente um recurso Android. Ter a mesma extensão não garante que um processador entenda a estrutura do seu documento.
Siga a convenção de diretórios do site #
Confirme estas escolhas de organização com base no carregador do seu projeto:
| Site | O que definir antes da tradução |
|---|---|
| Docusaurus | Quais documentos-fonte se tornam arquivos em i18n/<locale>/docusaurus-plugin-content-docs/current/ e quais documentos versionados ou textos do tema têm entradas separadas. |
| Nextra | Se a configuração instalada carrega páginas por idioma, dicionários ou outra árvore de conteúdo; mapeie cada entrada separadamente. |
| Hugo | Quais arquivos em content/<locale>/ compartilham a mesma identidade de conteúdo traduzido e como os links entre idiomas são resolvidos. |
| Astro | Quais coleções de conteúdo por idioma e dicionários de interface alimentam cada rota. |
| VitePress | Qual prefixo de diretório por idioma e qual configuração de navegação geram as páginas traduzidas. |
| MkDocs | Qual plugin de i18n e qual organização de documentos por idioma o projeto instalado usa. |
Neste exemplo com Docusaurus e documentos-fonte em docs/, instale e vincule a CLI a partir da raiz do projeto:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo linkMantenha os IDs da organização e do engine de localização em .lingo/config.json. Como esses caminhos de origem não contêm um idioma, substitua a entrada do arquivo por um modelo de saída explícito:
{
"pattern": "docs/**/*.md",
"sourceRoot": "docs",
"targetPath": "i18n/[locale]/docusaurus-plugin-content-docs/current/[path]"
}Para docs/setup/install.md, [path] se torna setup/install.md, de modo que a saída em espanhol vai para i18n/es/docusaurus-plugin-content-docs/current/setup/install.md. Confirme se o plugin e a versão instalados consomem esse diretório. Configuração explica a validação de modelos e as regras de colisão.
Traduza com critério os campos visíveis dos documentos #
Para Markdown, selecione os campos de metadados iniciais que os leitores veem, como título e descrição. Mantenha os metadados de identidade e publicação inalterados. Para MDX e Markdoc, identifique também as propriedades de componentes visíveis ao leitor, como o título de uma caixa de destaque. As propriedades que controlam o comportamento e os nomes de componentes pertencem ao esquema da aplicação.
Use o processador adequado em vez de presumir que todos os arquivos da família Markdown são intercambiáveis. Um documento Markdoc armazenado como .md precisa ter o formato markdoc definido explicitamente para ser processado como Markdoc. Consulte Markdown, MDX e Markdoc para conhecer os limites de seleção e reconstrução. Preserve os blocos de código delimitados como evidência executável; traduza a explicação ao redor deles em vez de alterar os comandos.
Execute o preenchimento dos arquivos ausentes:
lingo push --backfill-missing --waitApós a conclusão, gere o site e abra a rota de destino gerada. Verifique o título, a descrição, o corpo, os componentes personalizados, o bloco de código e um link. Se os IDs dos títulos forem derivados do texto, teste explicitamente os links para fragmentos traduzidos. Mesmo preservada, uma URL precisa apontar para um destino existente. O guia de Markdoc com Next.js apresenta um exemplo de carregamento por idioma.
Respeite os contratos dos catálogos estruturados #
Traduza os valores de texto de JSON e YAML genérico e proteja IDs, endpoints e outros dados não linguísticos com os controles de chaves do processador. Defina format: "yaml" explicitamente para YAML genérico na configuração de origem da CLI atual: inferir o formato pela extensão não basta para permitir o envio de uma origem YAML não configurada. Use yaml-root-key quando o idioma for a chave raiz e yaml-openapi quando a estrutura for um documento OpenAPI. Mantenha TypeScript e PHP nos formatos de catálogo compatíveis; traduzir um arquivo não permite avaliar código-fonte arbitrário com segurança.
Para PO, mantenha as identidades das mensagens, o contexto, a estrutura de plural e a etapa de compilação usada pelo destino. Para XLIFF, preserve a estrutura de origem/destino e dos marcadores de posição da variante compatível. Verifique a importação ou a compilação no sistema que de fato consome os arquivos, em vez de apenas conferir se o arquivo de saída existe.
Arquivos .txt de texto simples, como descrições de aplicativos em lojas, são traduzidos linha por linha, mantendo as linhas do original. Inclua .txt no padrão de arquivos, como em metadata/en/*.txt, ou defina "format": "txt": um padrão abrangente como docs/en/**/* não seleciona esses arquivos. Consulte Texto simples. Uma tabela CSV com uma coluna por idioma é traduzida no próprio arquivo: inclua .csv no padrão ou defina "format": "csv", conforme descrito em CSV. A CLI atual não oferece um arquivo CSV por idioma, WebVTT ou Java .properties como formatos configuráveis. A referência de formatos da CLI v0 é voltada a quem já utiliza esses fluxos de trabalho antigos; os comandos e as configurações apresentados nela são específicos dessa versão. Use a referência de migração para escolher uma opção compatível sem que esses recursos sejam descartados sem aviso.
Confira as legendas junto com a mídia #
Para SRT, traduza o texto das legendas e compare os índices e a marcação de tempo com o original. Reproduza cenas representativas com as legendas no idioma de destino. Verifique a extensão do texto para leitura, as quebras de linha, o contexto de quem fala e as tags de formatação no reprodutor que será usado. Preservar a marcação de tempo não garante que uma legenda traduzida possa ser lida dentro do intervalo disponível. Consulte SubRip para conhecer o contrato do arquivo; não o substitua por WebVTT só porque ambos são formatos de legenda.
Amplie a partir do processo de entrega validado #
Mantenha juntos a configuração, os arquivos-fonte, as traduções aceitas e o Lockfile da CLI. Após alterar um parágrafo, use lingo push --wait para processar as diferenças como de costume. Depois, compare esse parágrafo e uma seção inalterada no destino. Mantenha a versão anterior do original associada à sua tradução; reorganizar a estrutura dos documentos pode tornar a reutilização ambígua. Um padrão posicional usa uma semântica diferente de planejamento por escopo. Use o workflow de estimativa antes de uma retradução ampla e trate as estimativas como informações de planejamento, não como cotações de preço.
Quando as correções locais nas traduções precisarem de proteção contra divergências, envie sem --wait e inspecione lingo pull --dry-run antes de recuperar os resultados; a gravação direta após a espera não conta com essa etapa de controle. Siga Preservar traduções revisadas.
Escolha o GitHub App ou as receitas de CI assim que um grupo for compilado corretamente. Mantenha a compilação do site, a validação do esquema, as verificações de links e a revisão de conteúdo nesse ciclo; lingo check não comprova que o documento esteja completo. Cada atualização deve deixar uma página legível no idioma de destino e uma revisão dos arquivos-fonte que a equipe possa usar na próxima alteração.