Localizar conteúdo estático

Mapeie os documentos e catálogos traduzidos para os ficheiros que o seu site ou renderizador utiliza e verifique a estrutura, as ligações e o resultado final.

A árvore de ficheiros de origem do seu site já associa os artigos às rotas, aos metadados, à navegação e a um renderizador. Adicione os ficheiros traduzidos num local onde esse sistema os possa carregar. O primeiro resultado útil é uma página completa no idioma de destino, na rota prevista, com ligações funcionais e os mesmos exemplos de código do original.

Faça o inventário dos ficheiros por sistema que os utiliza #

Separe os documentos extensos dos catálogos estruturados e dos recursos especializados. Markdown, MDX e Markdoc precisam de um renderizador e de um esquema. Os catálogos JSON, YAML, TypeScript e PHP precisam de um carregador. PO e XLIFF ligam-se aos seus próprios sistemas de mensagens. O SRT insere-se num workflow de conteúdos multimédia com marcação temporal.

Escolha um ficheiro de origem representativo de cada grupo e identifique o caminho de saída e o carregador que o irá utilizar. Mantenha os ficheiros de destino gerados fora dos padrões de seleção dos ficheiros de origem. Preserve os IDs dos documentos, os URLs, os exemplos de código, as chaves dos catálogos e os atributos dos componentes cujos valores controlam o comportamento.

Use Formatos para selecionar o processador adequado. O YAML comum difere do YAML com o idioma na raiz e do YAML OpenAPI. .xml não identifica automaticamente um recurso Android. O facto de partilharem uma extensão não garante que um processador compreenda a estrutura do seu documento.

Siga a convenção de diretórios do site #

Confirme estas opções de organização tendo em conta o carregador do seu projeto:

SiteO que definir antes da tradução
DocusaurusQue documentos de origem dão origem a ficheiros em i18n/<locale>/docusaurus-plugin-content-docs/current/ e que documentos versionados ou cadeias de texto do tema têm entradas separadas.
NextraSe a configuração instalada carrega páginas por idioma, dicionários ou outra árvore de conteúdos; mapeie cada entrada separadamente.
HugoQue ficheiros em content/<locale>/ correspondem a versões traduzidas do mesmo conteúdo e como são resolvidas as ligações entre idiomas.
AstroQue coleções de conteúdos e dicionários da interface específicos de cada idioma alimentam cada rota.
VitePressQue prefixo de diretório de idioma e que configuração de navegação geram as páginas traduzidas.
MkDocsQue extensão i18n e que organização de documentos por idioma são usadas no projeto instalado.

Num exemplo com Docusaurus e documentos de origem em docs/, instale e associe a CLI a partir da raiz do projeto:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo link

Mantenha os IDs da organização e do motor de localização em .lingo/config.json. Como estes caminhos de origem não contêm um idioma, substitua a entrada do ficheiro por um modelo de saída explícito:

json
{
  "pattern": "docs/**/*.md",
  "sourceRoot": "docs",
  "targetPath": "i18n/[locale]/docusaurus-plugin-content-docs/current/[path]"
}

Para docs/setup/install.md, [path] passa a setup/install.md, pelo que os ficheiros em espanhol são guardados em i18n/es/docusaurus-plugin-content-docs/current/setup/install.md. Confirme que a extensão e a versão instaladas utilizam esse diretório. Configuração explica a validação dos modelos e as regras de colisão.

Escolha com critério os campos visíveis dos documentos a traduzir #

Para Markdown, selecione os campos dos metadados iniciais que os leitores veem, como o título e a descrição. Mantenha inalterados os metadados de identidade e de publicação. Para MDX e Markdoc, identifique também as propriedades dos componentes apresentadas aos leitores, como o título de uma caixa de destaque. As propriedades que controlam o comportamento e os nomes dos componentes pertencem ao esquema da aplicação.

Use o processador adequado, em vez de partir do princípio de que todos os ficheiros da família Markdown são intercambiáveis. Um documento Markdoc guardado como .md precisa de um formato markdoc explícito 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 prova executável; traduza a explicação que os acompanha, em vez de alterar os comandos.

Execute o preenchimento dos ficheiros em falta:

sh
lingo push --backfill-missing --wait

Quando a operação terminar, compile o site e abra a rota de destino gerada. Verifique o título, a descrição, o corpo do texto, os componentes personalizados, o bloco de código e uma ligação. Se os IDs dos títulos forem gerados a partir do texto, teste explicitamente as ligações para fragmentos traduzidos. Mesmo que um URL seja preservado, o respetivo destino tem de existir. O guia de Markdoc com Next.js apresenta um exemplo de carregamento específico de um idioma.

Respeite os contratos dos catálogos estruturados #

Traduza os valores de texto de JSON e YAML genérico, protegendo os IDs, os pontos de extremidade e outros dados não linguísticos com os controlos de chaves do processador. Defina format: "yaml" explicitamente para YAML genérico na configuração de origem da CLI atual: deduzir o formato apenas 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 de raiz e yaml-openapi quando a estrutura for um documento OpenAPI. Restrinja TypeScript e PHP aos formatos de catálogo suportados; a tradução de um ficheiro não avalia código-fonte arbitrário de forma segura.

Para PO, mantenha as identidades das mensagens, o contexto, a estrutura de plurais 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 suportada. Verifique a importação ou a compilação no sistema que efetivamente utiliza os ficheiros, em vez de confirmar apenas que existe um ficheiro de saída.

Os ficheiros de texto simples .txt, como as descrições de aplicações nas lojas de aplicações, são traduzidos linha a linha, preservando as linhas do original. Inclua .txt no padrão de ficheiros, como em metadata/en/*.txt, ou defina "format": "txt": um padrão abrangente como docs/en/**/* não os seleciona. Consulte Texto simples. Uma tabela CSV com uma coluna por idioma é traduzida no próprio ficheiro: inclua .csv no padrão ou defina "format": "csv", conforme descrito em CSV. A CLI atual não disponibiliza as opções de um ficheiro CSV por idioma, WebVTT ou .properties de Java como formatos configuráveis. A referência de formatos da CLI v0 destina-se a quem já tem esses fluxos de trabalho mais antigos instalados; os respetivos comandos e configurações são específicos dessa versão. Consulte a referência de migração para escolher uma alternativa compatível sem que esses recursos sejam descartados sem aviso.

Verifique as legendas com o conteúdo multimédia #

Para SRT, traduza o texto das legendas e compare os índices e os tempos com o original. Reproduza cenas representativas com as legendas no idioma de destino. Verifique a extensão do texto a ler, as quebras de linha, o contexto de quem fala e as etiquetas de formatação no leitor que será efetivamente utilizado. Preservar as marcas temporais não garante que uma legenda traduzida possa ser lida no respetivo intervalo. Consulte SubRip para conhecer o contrato do ficheiro; não o substitua por WebVTT só porque ambos são formatos de legendas.

Aumente a escala a partir do processo de entrega validado #

Mantenha juntos a configuração, os ficheiros de origem, os ficheiros de destino aceites e o Lockfile da CLI. Depois de alterar um parágrafo, use lingo push --wait para processar as diferenças habituais e compare esse parágrafo e uma secção inalterada no destino. Mantenha a versão anterior da origem associada ao respetivo destino; a reorganização da estrutura dos documentos pode tornar a reutilização ambígua. Um padrão posicional utiliza uma semântica diferente de planeamento por âmbito. Use o workflow de estimativa antes de uma retradução alargada, tratando as estimativas como informação de planeamento e não como orçamentos.

Quando as correções locais no destino precisarem de proteção contra divergências, submeta sem --wait e inspecione lingo pull --dry-run antes de obter os resultados; a gravação direta após a espera não inclui essa etapa de controlo. Siga Preservar traduções revistas.

Escolha a GitHub App ou as receitas de CI assim que um grupo compilar corretamente. Mantenha a compilação do site, a validação do esquema, a verificação de ligações e a revisão de conteúdos nesse ciclo; lingo check não garante que o documento esteja completo. Cada atualização deve deixar uma página de destino legível e uma revisão da origem que a equipa possa usar na alteração seguinte.