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

— Для виявлення спеціальних підкласів рядків потрібен beautifulsoup4 4.9.0 і вище.

• Цільові вузли слід зібрати перед заміною, щоб уникнути зміни дерева 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 = "欢迎用户";. Деякі вільні інтерпретатори можуть не повідомити про помилку, але якщо призначення змінних передбачає логічне судження або інтернаціоналізоване відображення ключ-значення, логіка програми не працюватиме. Якщо процес перекладу змінює тип лапок або екрановані символи, розбір сценарію може бути перервано, і вся сторінка відображатиметься як білий екран.

Реалізація 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 надає багатоформатний портал перекладу документів. На офіційному веб-сайті представлені такі функції, як OCR, глосарій і двомовне порівняння. Якщо команда хоче розпочати обробку безпосередньо з файлу, цей шлях можна оцінити за допомогою реальних зразків. Будь ласка, використовуйте десенсибілізовані файли, на завантаження яких у вас є дозвіл, і скористайтеся прапорцями в цій статті, щоб переглянути результати. Це не стосується тверджень про те, що 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. Чи можна використовувати його безпосередньо на реальних файлах?

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

📝 Підсумок

Ключ до перекладу веб-сторінки полягає в тому, щоб спочатку визначити тип вузла, а потім вирішити, чи можна його замінити. Явно відфільтруйте спеціальні рядки, такі як сценарій, таблиця стилів і коментар, і використовуйте матрицю прийняття для перегляду результатів, щоб текст можна було перекласти, забезпечуючи при цьому нормальну роботу сторінки.

Спробуйте зараз: завантажте документ, щоб розпочати переклад, зберігаючи вихідний макет