Při překladu webových stránek nenahrazujte celý HTML: zpracujte pouze povolené textové uzly

Při překladu webových stránek není prvním problémem, se kterým se mnoho lidí setká, že překlad je nepřesný, ale že jsou skripty a styly překládány společně. Například poté, co jsou názvy proměnných v <script> a názvy tříd v <style> nahrazeny textem, může prohlížeč přímo hlásit chybu a styl stránky bude zpackaný. Tento článek je určen pro vývojáře a dokumentační týmy, kteří potřebují zvládnout překlad HTML stránek v Pythonu.

Na konci tohoto článku budete vědět, jak používat typ NavigableString společnosti Beautiful Soup k identifikaci textových uzlů, které mohou být nahrazeny, uvidíte příklad bezpečného nahrazení a budete vědět, jaké hranice a kritéria přijetí je třeba před dodáním zkontrolovat. Všechny ukázky v tomto článku jsou syntetická data a kód byl ukázkově zkontrolován v izolovaném prostředí, ale to nepředstavuje záruku všech skutečných souborů nebo efektů produktu. Před manipulací s důležitými dokumenty si prosím uschovejte originály.

Jak nahradit pouze hlavní text v překladu webové stránky? Závěr jednou větou

Před nahrazením nejprve vylučte speciální řetězce, jako jsou Script, Stylesheet a Comment, pomocí posouzení typu a nahraďte pouze obyčejný NavigableString.

Proč musí NavigableString nejprve posoudit typ?

Mnoho vývojářů je zvyklých používat soup.find_all(text=True) nebo procházet .strings k získání textu stránky. Tato metoda funguje, pokud jde o čistou extrakci obsahu, ale je riskantní v překladových scénářích. Beautiful Soup 4.9.0 později zavedlo speciální řetězcové podtřídy pro HTML dokumenty. Přestože dědí z NavigableString, jejich sémantika je zcela odlišná.

• Comment: Komentář
• Script: Kód JavaScript
• Stylesheet: styl CSS
• Template: Obsah šablony HTML

Pokud na tyto objekty zavoláte .replace_with(), obsah neprezentační vrstvy bude upraven. Například překlad var userName = "admin"; na var 用户名 = "管理员"; povede k chybě syntaxe JS. Správný přístup je provést před substitucí tvrzení typu, aby bylo zajištěno, že cílem je pouze obyčejná NavigableString a nikoli funkční podtřída.

Při zpracování XML dokumentů je potřeba dávat pozor i na speciální typy jako CData, ProcessingInstruction atd. Neměly by se také překládat jako běžný text.

Příklad syntézy: hranice mezi správným a nesprávným

Pro demonstraci tohoto mechanismu je níže zkonstruován syntetický fragment HTML obsahující smíšený obsah, který pokrývá čtyři typy uzlů: tělo, skript, styl a komentář.

Vstupní vzorek (syntetický příklad):

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

Očekávaný správný výstup:

• Pouze přímý textový uzel "Vítaný uživatel" v tagu <div> je nahrazen "Vítaným uživatelem".
• Struny uvnitř <script> zůstávají nedotčené.
• Obsah <style> zůstává nezměněn a obsah anotace zůstává nezměněn.
• Hierarchický vztah DOM je zcela zachován.

Typický nesprávný vstup a důsledky:

Pokud nepřidáte kontrolu typu a přímo provedete globální nahrazení na všech NavigableString, tag <script> se stane var msg = "欢迎用户";. Některé volné interprety nemusí hlásit chybu, ale pokud přiřazení proměnných zahrnuje logické posouzení nebo internacionalizované mapování klíč-hodnota, logika programu selže. Pokud proces překladu změní typ citace nebo znaky escape, může být analýza skriptu přerušena a celá stránka se zobrazí jako bílá obrazovka.

Python implementace bezpečného nahrazení textových uzlů

Následující kód ukazuje, jak bezpečně zpracovat výše uvedený syntetický vzorek v paměti. Příklad závisí na beautifulsoup4. Spusťte jej prosím v prostředí, které uzamkne závislosti. Verze se doporučuje 4.9.0 nebo vyšší, aby byla podporována speciální detekce podtříd řetězců. Kód nezahrnuje síťové požadavky, ale pouze demonstruje logiku analýzy a nahrazování.

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

Klíčem k tomuto kódu jsou četné kontroly isinstance. I když je Beautiful Soup starší a nepodporuje třídy jako Script, můžete zkontrolovat název nadřazené značky jako záložní řešení, ale vždy je preferována explicitní kontrola typu. Použití replace_with s explicitní konstrukcí NavigableString je bezpečnější než přímé přiřazení. Dokáže správně zpracovat referenční vztah uzlů ve stromu a vyhnout se osiřelým objektům nebo záměně typů.

Kritéria přijetí a hranice manuální kontroly

Typové filtrování je pouze první linií obrany. Před dodáním je třeba vytvořit jasnou matici akceptace, která bude rozlišovat mezi automatizovaným zpracováním a manuálním zásahem, aby se zabránilo slepé důvěře ve výstup skriptu.

Tato tabulka je vhodná pouze pro ověření logiky na úrovni demonstrace kódu. Efekt end-to-end vyžaduje ověření výsledků vykreslování ve skutečném prohlížeči. Přestože atributy content tagu <meta>, tagy ARIA atd. nepatří do NavigableString, může být také nutné je přeložit. To vyžaduje, aby měl analyzátor schopnosti procházení atributů, a to přesahuje rozsah tohoto uzlu tohoto článku.

Další čtení

• Krásná polévka Oficiální dokumentace: NavigableString
• Krásná polévka Oficiální dokumentace: Druhy objektů

Použijte kontrolní seznamy pro překlad dokumentů

Text, odkazy, kód a struktura dokumentů webových stránek musí být zpracovány samostatně. Přidejte chráněné části do seznamu přijatelnosti a poté vyhodnoťte čitelnost a prezentaci stránky po překladu.

OmniDoc poskytuje portál pro překlad dokumentů ve více formátech. Oficiální webová stránka představuje funkce, jako je OCR, glosář a dvojjazyčné srovnání. Pokud chce tým zahájit zpracování přímo ze souboru, lze tuto cestu vyhodnotit reálnými vzorky. Použijte prosím znecitlivěné soubory, k jejichž nahrávání máte oprávnění, a ke kontrole výsledků použijte zaškrtávací položky v tomto článku. To nezahrnuje tvrzení, že OmniDoc používá open source knihovny nebo interní algoritmy popsané v tomto článku a příklady nenahrazují testování výkonu produktu.

📊 Srovnání jádra

🎯 Která metoda je pro vás vhodná?

pokud jste……

• Zvládněte překlad těla webové stránky: filtrujte s explicitním typem a nahraďte pouze prostý NavigableString.
• Obsah v <script> a <style> je třeba přeložit: Nejprve potvrďte, zda se jedná o zdroj i18n, a poté se rozhodněte, zda jej chcete zpracovat. Ve výchozím nastavení je přeskočen.
• Použití starší verze Beautiful Soup: Pro posouzení downgradu můžete použít název nadřazené značky, ale doporučuje se upgradovat na 4.9.0 nebo vyšší.
• Překlad alt, title a dalších atributů: Logiku procházení atributů je třeba zapsat samostatně a tato metoda tuto část nepokrývá.

❓ Často kladené otázky (FAQ)

1. Mohu přímo použít find_all(text=True) k získání textu k překladu?

Tato metoda je vhodná pro čistou extrakci obsahu, ale v překladových scénářích budou speciální podkategorie jako Script a Stylesheet také považovány za běžný text, což je riskantní.

2. Co mám dělat, když je verze Krásné polévky starší?

Je možné zkontrolovat název nadřazené značky jako scénář downgrade, ale vždy je preferována explicitní kontrola typu a doporučuje se verze 4.9.0+.

3. Délka HTML se po výměně výrazně změní. Čemu bychom měli věnovat pozornost?

Pokud se délka změní o více než 300 %, mělo by být označeno varování a překlad by měl být zkontrolován, zda neobsahuje speciální znaky bez escapování, aby se zabránilo vkládání nebo přetečení rozvržení.

4. Budou hodnoty atributů jako alt a title zpracovány tímto kódem?

Zvyklý. Hodnoty atributů jsou mimo rozsah tohoto článku a logiku procházení atributů je třeba psát samostatně.

5. Lze jej použít přímo na skutečné soubory?

Doporučuje se nejprve ponechat původní dokument a otestovat jej pomocí znecitlivěného dokumentu, k jehož nahrání máte oprávnění. Kód prošel kontrolou syntetického vzorku a nepředstavuje záruku všech skutečných souborů.

📝 Shrnutí

Klíčem k překladu webové stránky je nejprve identifikovat typ uzlu a poté rozhodnout, zda jej lze nahradit. Explicitně filtrujte speciální řetězce, jako je Script, Stylesheet a Comment, a použijte matici přijetí ke kontrole výsledků, aby bylo možné text přeložit a zároveň zajistit, aby stránka běžela normálně.

Vyzkoušejte to hned: Nahrajte dokument a začněte překládat při zachování původního rozvržení