Não substitua todo o HTML ao traduzir páginas da web: processe apenas nós de texto permitidos

Ao traduzir páginas da web, o primeiro problema que muitas pessoas encontram não é que a tradução seja imprecisa, mas que os scripts e estilos sejam traduzidos juntos. Por exemplo, depois que os nomes das variáveis em <script> e os nomes das classes em <style> são substituídos como texto, o navegador pode relatar diretamente um erro e o estilo da página ficará confuso. Este artigo é destinado a desenvolvedores e equipes de documentação que precisam lidar com a tradução de páginas HTML em Python.

Ao final deste artigo, você saberá como usar o tipo NavigableString do Beautiful Soup para identificar nós de texto que podem ser substituídos, ver um exemplo de substituição segura e saber quais limites e critérios de aceitação devem ser revisados antes da entrega. Os exemplos neste artigo são todos dados sintéticos e o código foi verificado em um ambiente isolado, mas isso não representa uma garantia de todos os arquivos reais ou efeitos do produto. Guarde os originais antes de manusear documentos importantes.

Como substituir apenas o corpo do texto na tradução de páginas web? Conclusão de uma frase

Antes da substituição, primeiro exclua strings especiais como Script, Stylesheet e Comment por meio de julgamento de tipo e substitua apenas NavigableString comum.

Por que NavigableString precisa primeiro julgar o tipo?

Muitos desenvolvedores estão acostumados a usar soup.find_all(text=True) ou percorrer .strings para obter o texto da página. Este método funciona quando se trata de extração pura de conteúdo, mas é arriscado em cenários de tradução. O Beautiful Soup 4.9.0 introduziu posteriormente subclasses de strings especiais para documentos HTML. Embora herdem de NavigableString, sua semântica é completamente diferente.

• Comment: Comentário
• Script: código JavaScript
• Stylesheet: estilo CSS
• Template: conteúdo do modelo HTML

Se você chamar .replace_with() nesses objetos, o conteúdo da camada de não apresentação será modificado. Por exemplo, traduzir var userName = "admin"; para var 用户名 = "管理员"; resultará em um erro de sintaxe JS. A abordagem correta é fazer uma asserção de tipo antes da substituição para garantir que o destino seja apenas um NavigableString simples e não uma subclasse funcional.

Ao processar documentos XML, você também precisa prestar atenção a tipos especiais como CData, ProcessingInstruction, etc. Eles também não devem ser traduzidos como texto comum.

Exemplo de síntese: a fronteira entre o correto e o incorreto

Para demonstrar esse mecanismo, um fragmento HTML sintético contendo conteúdo misto é construído abaixo, abrangendo quatro tipos de nós: corpo, script, estilo e comentário.

Amostra de entrada (exemplo sintético):

<div class="content">
  Welcome user
  <script>var msg = "Welcome user";</script>
  <style>.msg { color: red; }</style>
  <!-- Welcome user -->
</div>

Saída correta esperada:

• Somente o nó de texto direto "Usuário de boas-vindas" na tag <div> é substituído por "Usuário de boas-vindas".
• As strings em <script> permanecem intactas.
• O conteúdo de <style> permanece inalterado e o conteúdo da anotação permanece inalterado.
• O relacionamento hierárquico do DOM é completamente preservado.

Inserções incorretas típicas e consequências:

Se você não adicionar verificação de tipo e executar diretamente a substituição global em todos os NavigableString, a tag <script> se tornará var msg = "欢迎用户";. Alguns intérpretes soltos podem não reportar um erro, mas se a atribuição de variáveis envolver julgamento lógico ou mapeamento internacionalizado de valores-chave, a lógica do programa falhará. Se o processo de tradução alterar o tipo de citação ou os caracteres de escape, a análise do script poderá ser interrompida e a página inteira aparecerá como uma tela branca.

Implementação Python de substituição segura de nós de texto

O código a seguir mostra como lidar com segurança com o exemplo sintético acima na memória. O exemplo depende de beautifulsoup4. Execute-o em um ambiente que bloqueie as dependências. Recomenda-se que a versão seja 4.9.0 ou superior para suportar detecção especial de subclasses de strings. O código não inclui solicitações de rede, mas apenas demonstra a lógica de análise e substituição.

from bs4 import BeautifulSoup, NavigableString, Comment
# BS4 4.9.0+ 才引入 Script, Stylesheet 等子类
try:
    from bs4 import Script, Stylesheet, Template
    HAS_SPECIAL_STRINGS = True
except ImportError:
    HAS_SPECIAL_STRINGS = False

def safe_translate_text(html_content: str, translation_map: dict) -> str:
    """
    仅替换普通文本节点，跳过脚本、样式、注释及模板。
    :param html_content: 原始HTML字符串（若处理文件请先读取为字符串）
    :param translation_map: 原文到译文的映射字典
    :return: 替换后的HTML字符串
    """
    soup = BeautifulSoup(html_content, 'html.parser')

    # 收集所有需要处理的字符串节点
    # 注意：不能边遍历边修改，需先收集再处理
    targets = []
    for element in soup.descendants:
        if not isinstance(element, NavigableString):
            continue
        # 核心防护：排除特殊功能字符串
        if isinstance(element, Comment):
            continue
        if HAS_SPECIAL_STRINGS and isinstance(element, (Script, Stylesheet, Template)):
            continue
        # 可选：跳过纯空白节点以减少无效API调用
        if not str(element).strip():
            continue

        targets.append(element)

    # 执行安全替换
    for node in targets:
        original = str(node)
        if original in translation_map:
            # 显式创建NavigableString确保DOM引用完整性
            new_node = NavigableString(translation_map[original])
            node.replace_with(new_node)

    return str(soup)

# --- 合成数据验证 ---
SAMPLE_HTML = '''<div>Welcome user<script>var x="Welcome user";</script><!-- Welcome user --></div>'''
DICT_MAP = {"Welcome user": "欢迎用户"}

result = safe_translate_text(SAMPLE_HTML, DICT_MAP)
assert "欢迎用户" in result, "正文应被翻译"
assert 'var x="Welcome user";' in result, "脚本内容不应被修改"
assert "<!-- Welcome user -->" in result, "注释不应被修改"
print("逻辑校验通过（教学示例，非生产环境实测证明）")

A chave para este código são as múltiplas verificações isinstance. Mesmo que o Beautiful Soup seja mais antigo e não suporte classes como Script, você pode verificar o nome da tag pai como uma solução substituta, mas a verificação de tipo explícita é sempre preferida. Usar replace_with com construção NavigableString explícita é mais seguro do que atribuição direta. Ele pode manipular corretamente o relacionamento de referência dos nós na árvore e evitar objetos órfãos ou confusão de tipos.

Critérios de aceitação e limites de revisão manual

A filtragem de tipo é apenas a primeira linha de defesa. Antes da entrega, é necessário estabelecer uma matriz de aceitação clara para distinguir entre processamento automatizado e intervenção manual, a fim de evitar confiança cega na saída do script.

Esta tabela é adequada apenas para verificação lógica no nível de demonstração de código. O efeito ponta a ponta requer a verificação dos resultados da renderização em um navegador real. Embora os atributos content da tag <meta>, tags ARIA, etc. não pertençam a NavigableString, eles também podem precisar ser traduzidos. Isso exige que o analisador tenha recursos de passagem de atributos e está além do escopo deste nó deste artigo.

Leitura adicional

• Documentação oficial da Beautiful Soup: NavigableString
• Documentação oficial da Beautiful Soup: tipos de objetos

Use checklists para tradução de documentos

O texto, links, código e estrutura dos documentos da página web devem ser processados separadamente. Adicione as partes protegidas à lista de aceitação e avalie a legibilidade e a apresentação da página após a tradução.

OmniDoc fornece um portal de tradução de documentos multiformato. O site oficial apresenta funções como OCR, glossário e comparação bilíngue. Caso a equipe queira iniciar o processamento diretamente do arquivo, esse caminho pode ser avaliado com amostras reais. Use arquivos dessensibilizados que você tem permissão para carregar e use os itens de verificação neste artigo para revisar os resultados. Isso não envolve alegações de que o OmniDoc usa bibliotecas de código aberto ou algoritmos internos descritos neste artigo, e os exemplos não substituem os testes de desempenho do produto.

📊 Comparação principal

🎯 Qual método é adequado para você?

se você……

• Tratar da tradução do corpo da página da web: filtrar com tipo explícito e substituir apenas NavigableString simples.
• O conteúdo em <script> e <style> precisa ser traduzido: Primeiro confirme se é um recurso i18n e depois decida se deseja processá-lo. Ele é ignorado por padrão.
• Usando uma versão mais antiga do Beautiful Soup: Você pode usar o nome da tag pai para julgamento de downgrade, mas é recomendado atualizar para 4.9.0 ou superior.
• Para traduzir alt, title e outros atributos: A lógica de passagem de atributos precisa ser escrita separadamente e este método não cobre esta parte.

❓ Perguntas frequentes (FAQ)

1. Posso usar find_all(text=True) diretamente para obter o texto a ser traduzido?

Este método é adequado para extração pura de conteúdo, mas em cenários de tradução, subcategorias especiais como Script e Folha de Estilo também serão tratadas como texto comum, o que é arriscado.

2. O que devo fazer se a versão do Beautiful Soup for mais antiga?

É possível verificar o nome da tag pai como um cenário de downgrade, mas a verificação de tipo explícita é sempre preferida e a versão 4.9.0+ é recomendada.

3. O comprimento do HTML muda muito após a substituição. Em que devemos prestar atenção?

Um aviso deve ser sinalizado quando o comprimento muda em mais de 300%, e a tradução deve ser verificada quanto a caracteres especiais sem escape para evitar injeção ou estouro de layout.

4. Valores de atributos como alt e title serão processados por este código?

Não vai. Os valores dos atributos estão fora do escopo deste artigo e a lógica de passagem de atributos precisa ser escrita separadamente.

5. Pode ser usado diretamente em arquivos reais?

Recomenda-se primeiro manter o documento original e testá-lo com um documento dessensibilizado que você tenha permissão para carregar. O código passou na inspeção de amostra sintética e não representa uma garantia de todos os arquivos reais.

📝 Resumo

A chave para a tradução de páginas web é primeiro identificar o tipo de nó e depois decidir se ele pode ser substituído. Filtre explicitamente strings especiais, como Script, Folha de Estilo e Comentário, e use a matriz de aceitação para revisar os resultados, para que o texto possa ser traduzido e, ao mesmo tempo, garanta que a página possa ser executada normalmente.

Experimente agora: carregue o documento para iniciar a tradução, mantendo o layout original