Překlad technických dokumentů se nejvíce bojí překladu kódu: k ochraně bloků kódu použijte Beautiful Soup

Při překladu technických dokumentů je překlad user_id na „identifikátor uživatele"nebo změna atributu třídy v<div class="container"> nákladné a obtížně řešitelné. Tento typ chyby obvykle nezhroutí program, ale může způsobit, že zkopírovaný a vložený kód přímo ohlásí chybu nebo zneplatní příklady v dokumentaci API.

Řešení nespočívá v tom, jak chytrý je překladový stroj, ale v tom, zda fáze předběžného zpracování dokáže přesně oddělit přirozený jazyk a kód ve stromu DOM. Následující text nejprve vysvětlí, proč regulární výrazy nestačí, poté použije syntetické vzorky k demonstraci metody identifikace uzlů Beautiful Soup a nakonec uvede kritéria přijetí. Všechny příklady jsou syntetická data, před prací na důležitých souborech si prosím uschovejte originály.

Jak chránit kód při překladu technických dokumentů? Závěr jednou větou

Pomocí Beautiful Soup identifikujte kódové uzly ve stromu DOM, nejprve je zamaskujte nebo oddělte a poté posílejte pouze odstavce v přirozeném jazyce k překladu a jako standardy doručení použijte automatické ověřování a ruční kontrolu.

##Proč regulární výrazy nejsou dostatečné pro ochranu kódu

Mnoho týmů se před překladem pokusí nahradit úryvky kódu regulárními výrazy, ale tento přístup je ve struktuře HTML křehký. HTML není lineární text, ale vnořená stromová struktura. Značka <code> může obsahovat zvýraznění <span> nebo může být obalena značkou <a> za účelem vytvoření odkazu. Regulární výrazy nerozumí tomuto vztahu vnoření, což může snadno způsobit chyby při uzavírání štítků nebo vynechat okrajové podmínky.

Pomocí analyzátorů, jako je Beautiful Soup, můžete upgradovat ochranu kódu z "string matching" na "node traversal". Podle Krásná polévka 4.15.0 Oficiální dokumentace mohou programy přímo manipulovat s objekty Tag ve stromu DOM, aniž by musely hledat specifické vzory znaků. Identifikací sémantických značek, jako jsou pre, code, kbd, samp, a prvků s třídami, jako jsou highlight, language-python atd., lze přesně zacílit oblast, kterou je třeba stínit, bez ohledu na to, jak složitá je její vnitřní struktura.

Příklad syntézy: správný výstup a hraniční past

Aby bylo možné ověřit logiku ochrany, je třeba sestavit explicitní sadu syntetických testovacích případů. Následující vstup se používá pouze k demonstraci logiky analýzy. Nejedná se o skutečná výrobní data a nezahrnuje žádné externí čtení souborů.

Syntetický vstup HTML:

<p>请运行 <code class="cmd">pip install -r requirements.txt</code> 来安装依赖。</p>
<pre><code># 初始化配置
config = {"timeout": 30}</code></pre>
<p>注意：<var>timeout</var> 参数单位为秒。</p>

Očekávané výsledky extrakce: Překladový systém by měl obdržet pouze následující odstavec s prostým textem, přičemž část kódu bude nahrazena zástupnými symboly nebo zcela odstraněna:

1. "Pro instalaci závislostí spusťte [CODE_0]."
2. "Poznámka: Jednotkou parametru [VAR_0] jsou sekundy."

Obsah v bloku <pre> by se neměl objevit v textovém proudu, který má být přeložen, ani by se neměl exportovat s původními bajty nezměněnými.

Typické chyby a zpracování hranic:

• Vnořené značky: Pokud v <code><b>bold_code</b></code> extrahujete pouze code.string, dostanete Žádné, protože obsah je umístěn v podřízeném uzlu b. Mělo by se použít get_text() nebo rekurzivní procházení potomků.
• Uniklá hodnota atributu: Cílem překladu <a href="/api/v1/users">用户接口</a> je pouze „uživatelské rozhraní", hodnota atributuhref musí být uzamčena. Pokud je celá značka převedena na řetězec a odeslána k překladu, může být adresa URL poškozena.
• Značka pseudokódu: <div class="code-snippet"> není standardní sémantická značka a musí být navíc zachycena prostřednictvím whitelistu názvů třídy CSS, jinak bude považována za běžný překlad odstavce.

Implementace identifikace kódového uzlu na základě stromu DOM

Následující příklad Pythonu ukazuje, jak používat Beautiful Soup k procházení stromu dokumentu a rozlišování mezi přeložitelným textem a chráněným kódem. Tento skript je výukovou demonstrací čistě paměťových operací a neobsahuje síťové požadavky, příkazy Shell ani zápis souborů. Doporučuje se spouštět v prostředí beautifulsoup4>=4.15.0.

from bs4 import BeautifulSoup, NavigableString, Tag

# 合成示例：包含内联代码、代码块及普通文本（仅用于演示，非真实数据）
HTML_SAMPLE = """
<article>
  <p>使用 <code class="cli">kubectl get pods</code> 查看状态。</p>
  <pre><code>def hello():
    print("Hello World")</code></pre>
  <p>返回值 <var>result</var> 可能为空。</p>
</article>
"""

# 定义需要整体保护的标签集合
PROTECTED_TAGS = {'pre', 'code', 'kbd', 'samp', 'var'}

def extract_translatable_segments(html_content: str) -> list[dict]:
    """
    提取HTML中的文本片段并标记是否可翻译。
    注意：此为教学演示代码，生产环境需增加占位符生成与属性保护逻辑。
    """
    soup = BeautifulSoup(html_content, 'html.parser')
    segments = []

    # 遍历所有文本节点，而非仅顶层标签
    for element in soup.descendants:
        if isinstance(element, NavigableString):
            # 检查父链上是否存在受保护标签
            parent_chain = list(element.parents)
            is_protected = any(
                p.name in PROTECTED_TAGS 
                for p in parent_chain 
                if isinstance(p, Tag)
            )

            text = str(element).strip()
            if not text:
                continue

            segments.append({
                'text': text,
                'translatable': not is_protected,
                'context': element.parent.name if element.parent else 'root'
            })
    return segments

# 执行提取并断言预期行为
results = extract_translatable_segments(HTML_SAMPLE)
translatable_texts = [s['text'] for s in results if s['translatable']]
protected_texts = [s['text'] for s in results if not s['translatable']]

# 验证：普通文本应被标记为可翻译
assert any('查看状态' in t for t in translatable_texts), "普通文本未被识别"
# 验证：代码内容不应出现在可翻译列表中
assert not any('kubectl' in t for t in translatable_texts), "内联代码泄露至翻译区"
assert not any('print' in t for t in translatable_texts), "代码块内容泄露至翻译区"
# 验证：受保护内容被正确归类
assert any('kubectl' in t for t in protected_texts), "内联代码未被保护"

print(f"可翻译片段数: {len(translatable_texts)}")
print(f"受保护片段数: {len(protected_texts)}")

Klíčem k tomuto kódu je kontrola řetězu pro element.parents. I když je <code> vnořeno do <p>, textové uzly uvnitř jsou správně označeny jako nepřeložitelné. Je třeba poznamenat, že se jedná pouze o okrajovou ukázku extrakce a ověřování, nikoli o kompletní systém nahrazování překladu. Ve skutečné produkci je také potřeba zpracovat zásypy zástupných symbolů a ochranu atributů.

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

Ochranu kódu nelze posuzovat pouze podle „běhu bez chyb". V následující tabulce jsou uvedeny akce přijetí, které by měly být provedeny před doručením, a také scénáře, které nelze pokrýt automatickými skripty a vyžadují ruční kontrolu.

Nelze použít: Výše uvedené automatické ověření se vztahuje pouze na dobře strukturovaný sémantický kód HTML. U čistých bloků kódu<div> + <span> generovaných vykreslováním Markdown, které postrádají sémantické značky nebo zatemněné a komprimované jednotlivé řádky HTML, nemusí analyzátor správně identifikovat hranice kódu. Takové dokumenty je potřeba nejprve naformátovat a vyčistit, případně přímo předat k ručnímu zpracování. Toto ověření navíc pouze zaručuje, že „kód nebude přeložen"a nezaručuje kvalitu překladu v přirozeném jazyce.

Použijte kontrolní seznam na skutečný dokument

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

OmniDoc (produktový portál) poskytuje portál pro překlad dokumentů ve více formátech a oficiální webové stránky zavádějí funkce OCR, glosář a dvojjazyčné porovnání. Pro týmy, které chtějí začít pracovat přímo se soubory, je to cesta, kterou stojí za to vyhodnotit pomocí reálných vzorků. 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. Neexistuje žádné tvrzení, že OmniDoc používá open source knihovny nebo interní algoritmy uvedené v tomto článku, ani tento příklad nenahrazuje testování výkonu produktu.

📊 Srovnání jádra

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

pokud jste……

• V dokumentu je mnoho kódů a příkazů: Upřednostněte použití sémantických značek k identifikaci uzlů kódu, nejprve je zakryjte a poté přeložte.
• Struktura bloku kódu je složitá a hluboce vnořená: Použijte get_text() nebo rekurzivní procházení, nečtěte pouze .string.
• Stránka používá vlastní kontejner kódu: Vytvořte whitelist pro třídu a během přijímání zkontrolujte míru návštěvnosti.
• Připravte se na oficiální doručení: Proveďte automatické ověření a ruční kontrolu současně. Nedívejte se jen na to, zda skript běží úspěšně.

❓ Často kladené otázky (FAQ)

1. Proč nemohu nahradit kód regulárními výrazy?

HTML je vnořená stromová struktura a pro regulární výrazy je obtížné porozumět vnořenému vztahu mezi <code>, <span> a <a>, což může snadno způsobit chyby při uzavírání štítků nebo chybějící hranice.

2. Je nutné překládat komentáře v blocích kódu?

Formulář pro přijetí doporučuje zkontrolovat, zda nejsou přeskočeny komentáře v blocích kódu. Pokud komentáře obsahují důležité popisy obchodní logiky, měly by být extrahovány samostatně a poté přeloženy.

3. Pokud při spuštění skriptu nedojde k chybě, znamená to, že není problém s ochranou kódu?

nemůže. Je také nutné porovnat strukturu DOM, zkontrolovat, zda se klíčové atributy změnily, zkontrolovat počet zástupných symbolů a provést ruční kontrolu.

4. Platí tato metoda pro všechny dokumenty?

žádný. U čistých bloků kódu div + span generovaných vykreslováním Markdown nebo komprimovaného jednořádkového HTML nemusí být analyzátor schopen správně identifikovat hranice kódu a musí být nejprve naformátován nebo předán ručnímu zpracování.

📝 Shrnutí

Klíčem k překladu technických dokumentů je použití stromu DOM k oddělení kódu a přirozeného jazyka před překladem a použití kontrolního seznamu pro akceptaci ke kontrole výsledků. Nejprve ověřte pravidla na syntetických vzorcích a poté znovu zkontrolujte se znecitlivěnými skutečnými dokumenty.

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