Ne remplacez pas l'intégralité du code HTML lors de la traduction de pages Web : traitez uniquement les nœuds de texte autorisés

Lors de la traduction de pages Web, le premier problème rencontré par de nombreuses personnes n’est pas que la traduction soit inexacte, mais que les scripts et les styles soient traduits ensemble. Par exemple, une fois les noms de variables dans <script> et les noms de classes dans <style> remplacés sous forme de texte, le navigateur peut signaler directement une erreur et le style de la page sera perturbé. Cet article est destiné aux développeurs et aux équipes de documentation qui doivent gérer la traduction de pages HTML en Python.

À la fin de cet article, vous saurez comment utiliser le type NavigableString de Beautiful Soup pour identifier les nœuds de texte qui peuvent être remplacés, voir un exemple de remplacement sûr et connaître les limites et les critères d'acceptation qui doivent être examinés avant la livraison. Les exemples de cet article sont tous des données synthétiques et le code a été vérifié par échantillons dans un environnement isolé, mais cela ne représente pas une garantie de tous les fichiers réels ou effets du produit. Veuillez conserver les originaux avant de manipuler des documents importants.

Comment remplacer uniquement le corps du texte dans la traduction d'une page Web ? Conclusion en une phrase

Avant le remplacement, excluez d'abord les chaînes spéciales telles que Script, Stylesheet et Comment via un jugement de type, et remplacez uniquement NavigableString ordinaire.

votre situation	Pratiques recommandées	raison
Le texte se trouve dans `<p>`, `<span>`, `<li>`	Autoriser la substitution	Appartient aux scénarios de traduction standards
Le texte se trouve dans `<script>`, `<style>`	forcer le saut	Une modification incorrecte peut entraîner des erreurs de syntaxe JS ou une confusion de style.
Le type de nœud est `Comment`	franchir	Les commentaires ne font pas partie du contenu d'affichage de la page
Le texte se trouve dans `<code>`, `<pre>`	Ignorer par défaut	Les exceptions courantes dans les documents techniques nécessitent une confirmation manuelle
Utiliser une ancienne version de Beautiful Soup	Vérifiez le nom de la balise parent comme scénario de rétrogradation	La vérification de type explicite est toujours préférée, la version 4.9.0 ou supérieure est recommandée

Pourquoi NavigableString doit-il d'abord effectuer un jugement de type ?

De nombreux développeurs sont habitués à utiliser soup.find_all(text=True) ou à parcourir .strings pour obtenir le texte de la page. Cette méthode fonctionne lorsqu'il s'agit d'extraction pure de contenu, mais elle est risquée dans les scénarios de traduction. Beautiful Soup 4.9.0 a introduit plus tard des sous-classes de chaînes spéciales pour les documents HTML. Bien qu’ils héritent de NavigableString, leur sémantique est complètement différente.

Comment : commentaire
Script : code JavaScript
Stylesheet : style CSS
Template : contenu du modèle HTML

Si vous appelez .replace_with() sur ces objets, le contenu du calque de non-présentation sera modifié. Par exemple, la traduction de var userName = "admin"; en var 用户名 = "管理员"; entraînera une erreur de syntaxe JS. L'approche correcte consiste à faire une assertion de type avant la substitution pour garantir que la cible n'est qu'un simple NavigableString et non une sous-classe fonctionnelle.

Lors du traitement de documents XML, vous devez également faire attention aux types spéciaux tels que CData, ProcessingInstruction, etc. Ils ne doivent pas non plus être traduits sous forme de texte ordinaire.

Exemple de synthèse : la frontière entre le correct et l'incorrect

Pour démontrer ce mécanisme, un fragment HTML synthétique contenant un contenu mixte est construit ci-dessous, couvrant quatre types de nœuds : corps, script, style et commentaire.

Échantillon d'entrée (exemple synthétique) :

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

Sortie correcte attendue :

Seul le nœud de texte direct "Bienvenue utilisateur" dans la balise <div> est remplacé par "Bienvenue utilisateur".
Les chaînes de <script> restent intactes.
Le contenu de <style> reste inchangé, et le contenu de l'annotation reste inchangé.
La relation hiérarchique DOM est entièrement préservée.

Saisie incorrecte typique et conséquences :

Si vous n'ajoutez pas de vérification de type et n'effectuez pas directement un remplacement global sur tous les NavigableString, la balise <script> deviendra var msg = "欢迎用户";. Certains interprètes lâches peuvent ne pas signaler d'erreur, mais si l'affectation de variables implique un jugement logique ou un mappage clé-valeur internationalisé, la logique du programme échouera. Si le processus de traduction modifie le type de citation ou les caractères d'échappement, l'analyse du script peut être interrompue et la page entière apparaîtra sous la forme d'un écran blanc.

Implémentation Python du remplacement sécurisé des nœuds de texte

Le code suivant montre comment gérer en toute sécurité l’échantillon synthétique ci-dessus en mémoire. L'exemple dépend de beautifulsoup4. Veuillez l'exécuter dans un environnement qui verrouille les dépendances. Il est recommandé que la version soit 4.9.0 ou supérieure pour prendre en charge la détection de sous-classes de chaînes spéciales. Le code n'inclut pas les requêtes réseau, mais démontre uniquement la logique d'analyse et de remplacement.

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("逻辑校验通过（教学示例，非生产环境实测证明）")

La clé de ce code réside dans les multiples contrôles isinstance. Même si Beautiful Soup est plus ancien et ne prend pas en charge des classes comme Script, vous pouvez vérifier le nom de la balise parent comme solution de secours, mais la vérification de type explicite est toujours préférable. L'utilisation de replace_with avec une construction NavigableString explicite est plus sûre que l'affectation directe. Il peut gérer correctement la relation de référence des nœuds dans l'arborescence et éviter les objets orphelins ou la confusion des types.

Critères d'acceptation et limites de révision manuelle

Le filtrage de type n’est que la première ligne de défense. Avant la livraison, une matrice d'acceptation claire doit être établie pour faire la distinction entre le traitement automatisé et l'intervention manuelle afin d'éviter une confiance aveugle dans la sortie du script.

Observer les phénomènes	Décisions de traitement automatisées	Conditions de déclenchement de l'examen manuel	Remarque
Le texte se trouve dans `<p>`, `<span>`, `<li>`	Autoriser la substitution	aucun	Scénario de traduction standard
Le texte se trouve dans `<script>`, `<style>`	forcer le saut	Données JSON de configuration suspectées trouvées	Besoin de confirmer s'il s'agit d'une ressource i18n
Le texte se trouve dans `<code>`, `<pre>`	Ignorer par défaut	Clairement étiqueté « Commentaires de code » ou « Chaînes de documentation »	Cas particuliers courants des documents techniques
Valeurs d'attribut telles que `alt`, `title`, `placeholder`	N'entre pas dans le cadre de cet article	La valeur de l'attribut contient une entité HTML ou une interpolation de variable	La logique de parcours de propriété doit être écrite séparément
Le type de nœud est `Comment`	franchir	Les annotations contiennent un texte explicatif pour les utilisateurs	Certains CMS utilisent des commentaires comme invites
La longueur HTML a été modifiée de plus de 300 % après le remplacement	Avertissement de drapeau	La traduction contient des caractères spéciaux non échappés	Empêcher l'injection ou le débordement de mise en page

Ce tableau ne convient que pour la vérification logique au niveau de la démonstration de code. L'effet de bout en bout nécessite une vérification des résultats du rendu dans un vrai navigateur. Bien que les attributs content de la balise <meta>, des balises ARIA, etc. n'appartiennent pas à NavigableString, ils peuvent également devoir être traduits. Cela nécessite que l'analyseur ait des capacités de traversée d'attributs et dépasse la portée de ce nœud de cet article.

Lectures complémentaires

Utilisez des listes de contrôle pour la traduction de documents

Le texte, les liens, le code et la structure des documents des pages Web doivent être traités séparément. Ajoutez les parties protégées à la liste d'acceptation, puis évaluez la lisibilité et la présentation de la page après traduction.

OmniDoc fournit un portail de traduction de documents multiformats. Le site officiel présente des fonctions telles que l'OCR, le glossaire et la comparaison bilingue. Si l’équipe souhaite démarrer le traitement directement à partir du fichier, ce chemin peut être évalué avec des échantillons réels. Veuillez utiliser les fichiers désensibilisés que vous êtes autorisé à télécharger et utilisez les éléments de vérification de cet article pour examiner les résultats. Cela n'implique pas l'affirmation selon laquelle OmniDoc utilise des bibliothèques open source ou des algorithmes internes décrits dans cet article, et les exemples ne remplacent pas les tests de performances du produit.

📊 Comparaison de base

pratique	que pourrait-il arriver	Situations applicables
Remplacement global de tous les nœuds de texte	Le contenu du script et du style est modifié et la structure DOM peut devenir invalide.	Ne convient pas aux scénarios de traduction
Filtrage de type `isinstance` explicite	Remplacez uniquement les nœuds de texte normaux, conservez les sous-classes fonctionnelles	option préférée
Jugement de dégradation basé sur le nom de la balise parent	Exclure les régions partielles sans vérification de type explicite	Alternative aux anciennes versions de Beautiful Soup

🎯 Quelle méthode vous convient ?

si tu……

Gérer la traduction du corps de la page Web : filtrer avec un type explicite et remplacer uniquement NavigableString.
Le contenu de <script> et <style> doit être traduit : confirmez d'abord s'il s'agit d'une ressource i18n, puis décidez s'il faut la traiter. Il est ignoré par défaut.
Utilisation d'une ancienne version de Beautiful Soup : vous pouvez utiliser le nom de la balise parent pour un jugement de rétrogradation, mais il est recommandé de passer à la version 4.9.0 ou supérieure.
Pour traduire alt, title et d'autres attributs : La logique de parcours des attributs doit être écrite séparément, et cette méthode ne couvre pas cette partie.

❓ Questions fréquemment posées (FAQ)

1. Puis-je utiliser directement `find_all(text=True)` pour obtenir le texte à traduire ?

Cette méthode convient à l'extraction pure de contenu, mais dans les scénarios de traduction, des sous-catégories spéciales telles que Script et Feuille de style seront également traitées comme du texte ordinaire, ce qui est risqué.

2. Que dois-je faire si la version de Beautiful Soup est plus ancienne ?

Il est possible de vérifier le nom de la balise parent dans le cadre d'un scénario de rétrogradation, mais la vérification de type explicite est toujours préférée et la version 4.9.0+ est recommandée.

3. La longueur du code HTML change considérablement après le remplacement. A quoi devons-nous faire attention ?

Un avertissement doit être signalé lorsque la longueur change de plus de 300 %, et la traduction doit être vérifiée pour détecter les caractères spéciaux non échappés afin d'éviter toute injection ou tout débordement de mise en page.

4. Les valeurs d'attribut telles que `alt` et `title` seront-elles traitées par ce code ?

Ne le fera pas. Les valeurs d'attribut sortent du cadre de cet article et la logique de parcours d'attribut doit être écrite séparément.

5. Peut-il être utilisé directement sur de vrais fichiers ?

Il est recommandé de conserver au préalable le document original et de le tester avec un document désensibilisé que vous êtes autorisé à télécharger. Le code a passé avec succès l'inspection de l'échantillon synthétique et ne représente pas une garantie de tous les fichiers réels.

📝Résumé

La clé de la traduction de pages Web consiste d’abord à identifier le type de nœud, puis à décider s’il peut être remplacé. Filtrez explicitement les chaînes spéciales telles que Script, Feuille de style et Commentaire, et utilisez la matrice d'acceptation pour examiner les résultats, afin que le texte puisse être traduit tout en garantissant que la page peut s'exécuter normalement.

Essayez-le maintenant : téléchargez le document pour lancer la traduction, en conservant la mise en page d'origine.