Не заменяйте весь HTML при переводе веб-страниц: обрабатываются только разрешенные текстовые узлы

— Целевые узлы должны быть собраны перед заменой, чтобы избежать изменения дерева DOM во время перемещения. — Проверка кода основана только на синтетических образцах, реальные файлы все равно необходимо просматривать и проверять вручную в браузере.

При переводе веб-страниц первая проблема, с которой сталкиваются многие люди, заключается не в неточном переводе, а в том, что сценарии и стили переводятся вместе. Например, после того, как имена переменных в <script> и имена классов в <style> будут заменены текстом, браузер может напрямую сообщить об ошибке, и стиль страницы будет испорчен. Эта статья предназначена для разработчиков и групп документации, которым необходимо выполнять перевод HTML-страниц в Python.

К концу этой статьи вы узнаете, как использовать тип NavigableString в Beautiful Soup для определения текстовых узлов, которые разрешено заменять, увидите пример безопасной замены и узнаете, какие границы и критерии приемки следует проверить перед поставкой. Все примеры в этой статье представляют собой синтетические данные, а код был проверен на образцах в изолированной среде, но это не является гарантией всех реальных файлов или эффектов продукта. Пожалуйста, сохраняйте оригиналы, прежде чем обращаться с важными документами.

Как заменить только основной текст при переводе веб-страницы? Вывод в одно предложение

Перед заменой сначала исключите специальные строки, такие как Script, Stylesheet и Comment, посредством определения типа, и замените только обычную NavigableString.

Почему NavigableString сначала необходимо определить тип?

Многие разработчики привыкли использовать soup.find_all(text=True) или проходить по .strings для получения текста страницы. Этот метод работает, когда речь идет о чистом извлечении контента, но рискован в сценариях перевода. Позднее в Beautiful Soup 4.9.0 были представлены специальные строковые подклассы для HTML-документов. Хотя они и наследуют от NavigableString, их семантика совершенно другая.

• Comment: Комментарий
• Script: код JavaScript.
• Stylesheet: стиль CSS.
• Template: содержимое HTML-шаблона.

Если вы вызовете .replace_with() для этих объектов, содержимое слоя, не связанного с представлением, будет изменено. Например, перевод var userName = "admin"; в var 用户名 = "管理员"; приведет к синтаксической ошибке JS. Правильный подход — сделать утверждение типа перед заменой, чтобы гарантировать, что целью является только простой NavigableString, а не функциональный подкласс.

При обработке XML-документов также необходимо обращать внимание на специальные типы, такие как CData, ProcessingInstruction и т. д. Их также не следует переводить как обычный текст.

Пример синтеза: граница между правильным и неправильным

Чтобы продемонстрировать этот механизм, ниже создан синтетический фрагмент HTML, содержащий смешанный контент, охватывающий четыре типа узлов: тело, сценарий, стиль и комментарий.

Входной образец (синтетический пример):

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

Ожидаемый правильный результат:

• Только текстовый узел «Добро пожаловать пользователь» в теге <div> заменяется на «Добро пожаловать пользователь».
• Строки внутри <script> остаются нетронутыми.
• Содержимое <style> остается неизменным, как и содержание аннотации.
• Иерархические отношения DOM полностью сохраняются.

Типичный неверный ввод и последствия:

Если вы не добавите проверку типов и напрямую выполните глобальную замену для всех NavigableString, тег <script> станет var msg = "欢迎用户";. Некоторые свободные интерпретаторы могут не сообщать об ошибке, но если назначение переменных предполагает логическое суждение или интернационализированное сопоставление ключей и значений, логика программы потерпит неудачу. Если в процессе перевода изменится тип кавычки или escape-символы, анализ скрипта может быть прерван, и вся страница отобразится в виде белого экрана.

Реализация Python безопасной замены текстовых узлов

Следующий код показывает, как безопасно обрабатывать приведенный выше синтетический образец в памяти. Пример зависит от beautifulsoup4. Пожалуйста, запустите его в среде, которая блокирует зависимости. Рекомендуется использовать версию 4.9.0 или выше для поддержки обнаружения специального подкласса строк. Код не включает сетевые запросы, а лишь демонстрирует логику синтаксического анализа и замены.

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

Ключом к этому коду являются многочисленные проверки isinstance. Даже если Beautiful Soup старше и не поддерживает такие классы, как Script, вы можете проверить имя родительского тега в качестве запасного решения, но явная проверка типа всегда предпочтительна. Использование replace_with с явной конструкцией NavigableString безопаснее, чем прямое присвоение. Он может правильно обрабатывать ссылочные отношения узлов в дереве и избегать бесхозных объектов или путаницы типов.

Критерии приемки и границы ручной проверки

Фильтрация типов — это только первая линия защиты. Перед доставкой необходимо создать четкую матрицу приемки, чтобы различать автоматическую обработку и ручное вмешательство, чтобы избежать слепого доверия к выходным данным сценария.

Эта таблица подходит только для проверки логики на уровне демонстрации кода. Сквозной эффект требует проверки результатов рендеринга в реальном браузере. Хотя атрибуты content тега <meta>, теги ARIA и т. д. не принадлежат NavigableString, их также может потребоваться перевести. Это требует от синтаксического анализатора возможности обхода атрибутов и выходит за рамки этого узла данной статьи.

Дальнейшее чтение

• Официальная документация Beautiful Soup: NavigableString
• Официальная документация Beautiful Soup: Виды объектов

Используйте контрольные списки для перевода документов

Текст, ссылки, код и структура документов веб-страниц должны обрабатываться отдельно. Добавьте защищенные части в список приемки, а затем оцените читаемость и представление страницы после перевода.

OmniDoc предоставляет многоформатный портал для перевода документов. На официальном сайте представлены такие функции, как распознавание текста, глоссарий и двуязычное сравнение. Если команда хочет начать обработку непосредственно из файла, этот путь можно оценить на реальных образцах. Используйте десенсибилизированные файлы, на загрузку которых у вас есть разрешение, и используйте элементы проверки в этой статье, чтобы просмотреть результаты. Это не подразумевает утверждений о том, что OmniDoc использует библиотеки с открытым исходным кодом или внутренние алгоритмы, описанные в этой статье, и приведенные примеры не заменяют тестирование производительности продукта.

📊 Сравнение ядра

🎯 Какой метод подходит вам?

если ты……

• Обрабатывать перевод тела веб-страницы: фильтровать по явному типу и заменять только обычную NavigableString.
• Содержимое <script> и <style> необходимо перевести: сначала подтвердите, является ли это ресурсом i18n, а затем решите, следует ли его обрабатывать. По умолчанию оно пропускается.
• Использование более старой версии Beautiful Soup: вы можете использовать имя родительского тега для принятия решения о переходе на более раннюю версию, но рекомендуется выполнить обновление до версии 4.9.0 или выше.
• Для перевода alt, title и других атрибутов: логику обхода атрибутов необходимо писать отдельно, и этот метод не охватывает эту часть.

❓ Часто задаваемые вопросы (FAQ)

1. Могу ли я напрямую использовать find_all(text=True) для получения текста для перевода?

Этот метод подходит для чистого извлечения контента, но в сценариях перевода специальные подкатегории, такие как «Сценарий» и «Таблица стилей», также будут обрабатываться как обычный текст, что рискованно.

2. Что делать, если версия Beautiful Soup старая?

Можно проверить имя родительского тега в качестве сценария перехода на более раннюю версию, но всегда предпочтительна явная проверка типа и рекомендуется версия 4.9.0+.

3. Длина HTML сильно меняется после замены. На что нам следует обратить внимание?

Предупреждение должно быть помечено, когда длина изменяется более чем на 300 %, а перевод должен быть проверен на наличие неэкранированных специальных символов, чтобы предотвратить внедрение или переполнение макета.

4. Будут ли этим кодом обрабатываться такие значения атрибутов, как alt и title?

Не будет. Значения атрибутов выходят за рамки этой статьи, и логику обхода атрибутов нужно писать отдельно.

5. Можно ли использовать его непосредственно с реальными файлами?

Рекомендуется сначала сохранить исходный документ и протестировать его на десенсибилизированном документе, на загрузку которого у вас есть разрешение. Код прошел синтетическую выборочную проверку и не является гарантией всех реальных файлов.

📝 Резюме

Ключ к переводу веб-страницы — сначала определить тип узла, а затем решить, можно ли его заменить. Явно фильтруйте специальные строки, такие как «Сценарий», «Таблица стилей» и «Комментарий», и используйте матрицу принятия для просмотра результатов, чтобы текст можно было перевести, гарантируя при этом нормальную работу страницы.

Попробуйте сейчас: загрузите документ, чтобы начать перевод, сохранив исходный макет.