Ao traduzir documentação técnica (Markdown), como lidar com blocos de código e o Front Matter?
“Se os blocos de código, o código inline e as configurações de cabeçalho (Front Matter) em documentação técnica forem traduzidos à força, a documentação tornar-se-á inutilizável.”
Análise da causa raiz
Verificação do conteúdo do código e dos marcadores
O processo atual extrai conteúdo para tradução de acordo com a estrutura Markdown. O código em linha pode ser extraído juntamente com o texto em redor, e os comentários nos blocos de código também podem entrar na tradução. Após a tradução, verifique marcadores como ``` e ` e a sintaxe e a lógica dos exemplos Python e JS. Não suponha que todas as áreas de código serão ignoradas.
Proteção dos metadados Front Matter
Para a configuração YAML no início do documento (Front Matter), comum em blogs estáticos como Jekyll/Hugo, o processo de extração atual não trata valores de campos como `title` e `description` como textos separados para tradução. Verifique manualmente os metadados após a tradução e preserve parâmetros de compilação como `date:` e `slug:`.
Verificação do código-fonte de tabelas Markdown
Após a tradução de tabelas Markdown, as alterações no comprimento do texto podem causar diferenças no alinhamento das colunas no código-fonte. Verifique o carácter `|`, a linha separadora e o conteúdo das células, e organize manualmente o código-fonte da tabela quando necessário.
Resumo da solução final
Desenvolvido especialmente para a comunidade open source e para developers, garantindo profissionalismo e legibilidade na transição entre diferentes idiomas em ficheiros README.md e tutoriais técnicos.