技術文書の翻訳はコードの翻訳を最も恐れます: コード ブロックを保護するために Beautiful Soup を使用します

技術文書の翻訳では、user_id を「ユーザー識別子」に変換したり、<div class="container"> のクラス属性を変更したりするのはコストがかかり、トラブルシューティングが困難です。通常、このタイプのエラーによってプログラムがクラッシュすることはありませんが、コピーして貼り付けたコードが直接エラーを報告したり、API ドキュメントの例が無効になったりする可能性があります。

解決策は、翻訳エンジンがどれほど賢いかではなく、前処理段階で自然言語と DOM ツリー内のコードを正確に分離できるかどうかにあります。以下では、最初に正規表現では不十分な理由を説明し、次に合成サンプルを使用して Beautiful Soup のノード識別方法を実証し、最後に許容基準を示します。すべての例は合成データです。重要なファイルを扱う前にオリジナルを保管してください。

技術文書を翻訳するときにコードを保護するにはどうすればよいですか?一文の結論

Beautiful Soup を使用して DOM ツリー内のコード ノードを識別し、最初にそれらをマスクまたはストリップしてから、自然言語の段落のみを翻訳に送信し、配信標準として自動検証と手動レビューを使用します。

##正規表現がコード保護に不十分な理由

多くのチームは、翻訳前にコード スニペットを正規表現に置き換えようとしますが、このアプローチは HTML 構造において脆弱です。 HTML は直線的なテキストではなく、入れ子になったツリー構造です。 <code> タグには、<span> の強調表示が含まれることも、<a> タグでラップされてリンクを形成することもできます。正規表現はこの入れ子関係を理解できないため、ラベルを閉じるエラーや境界条件のミスが簡単に発生する可能性があります。

Beautiful Soup のようなパーサーを使用すると、コード保護を「文字列マッチング」から「ノード トラバーサル」にアップグレードできます。美しいスープ 4.15.0 公式ドキュメントによると、プログラムは特定の文字パターンを探すことなく、DOM ツリー内の Tag オブジェクトを直接操作できます。 pre、code、kbd、samp などのセマンティック タグ、および highlight、language-python などのクラスを持つ要素を識別することにより、内部構造がどれほど複雑であっても、シールドする必要がある領域を正確にターゲットにすることができます。

合成例: 正しい出力と境界トラップ

保護ロジックを検証するには、明示的な合成テスト ケースのセットを構築する必要があります。次の入力は、解析ロジックを示すためにのみ使用されます。これは実際の運用データではなく、外部ファイルの読み取りは必要ありません。

合成入力 HTML:

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

期待される抽出結果: 翻訳システムは、コード部分がプレースホルダーに置き換えられるか完全に削除された、次のプレーン テキストの段落のみを受け取る必要があります。

1. 「[CODE_0] を実行して依存関係をインストールしてください。」
2. 「注: [VAR_0] パラメータの単位は秒です。」

<pre> ブロック内のコンテンツは、翻訳対象のテキスト ストリームに表示されるべきではなく、元のバイトを変更せずにエクスポートされるべきです。

典型的なエラーと境界処理:

• ネストされたタグ: <code><b>bold_code</b></code> では、code.string のみを抽出すると、コンテンツが子ノード b に配置されているため、None が返されます。 get_text() または子孫の再帰的走査を使用する必要があります。
• 属性値の漏洩: <a href="/api/v1/users">用户接口</a> の変換対象は「ユーザー インターフェイス」のみです。href 属性値はロックする必要があります。タグ全体が文字列に変換されて翻訳に送信されると、URL が破損する可能性があります。
• 疑似コード タグ: <div class="code-snippet"> は標準のセマンティック タグではないため、CSS クラス名のホワイトリストを通じてさらにキャプチャする必要があります。そうでない場合は、通常の段落翻訳として扱われます。

DOM ツリーに基づくコード ノード識別の実装

次の Python の例は、Beautiful Soup を使用してドキュメント ツリーをトラバースし、翻訳可能なテキストと保護されたコードを区別する方法を示しています。このスクリプトは純粋なメモリ操作の教育用デモンストレーションであり、ネットワーク リクエスト、シェル コマンド、ファイル書き込みは含まれません。 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)}")

このコードの鍵は、element.parents のチェーン チェックです。 <code> が <p> 内にネストされている場合でも、その内部のテキスト ノードは翻訳不可として正しくマークされます。これは抽出と検証の周辺的なデモンストレーションにすぎず、完全な翻訳置換システムではないことに注意してください。実際の運用では、プレースホルダーの埋め戻しや属性の保護も処理する必要があります。

受け入れ基準と手動レビューの境界

コードの保護は、「エラーなしで実行される」だけでは判断できません。次の表に、配信前に実行する必要がある受け入れアクションと、自動スクリプトではカバーできず手動レビューが必要なシナリオを示します。

該当なし: 上記の自動検証は、適切に構造化されたセマンティックな HTML にのみ適用されます。マークダウン レンダリングによって生成されたセマンティック タグのない純粋な <div> + <span> コード ブロック、または難読化および圧縮された HTML の単一行の場合、パーサーはコード境界を正しく識別できない可能性があります。このようなドキュメントは、最初にフォーマットしてクリーニングするか、手動処理に直接渡す必要があります。また、この検証は「コードが翻訳されない」ことを保証するだけであり、翻訳の自然言語品質を保証するものではありません。

チェックリストを実際のドキュメントに適用する

Web ドキュメントのテキスト、リンク、コード、構造は個別に処理する必要があります。保護された部分をアクセプタンスリストに追加し、翻訳後の読みやすさやページ表示効果を評価します。

OmniDoc (製品ポータル)はマルチフォーマット文書翻訳ポータルを提供しており、公式 Web サイトでは OCR、用語集、対訳比較機能が導入されています。ファイルから直接作業を開始したいと考えているチームにとって、これは実際のサンプルを使用して評価する価値のあるパスです。アップロード許可のある感度を下げたファイルを使用し、この記事のチェック項目を使用して結果を確認してください。 OmniDoc がこの記事で言及されているオープン ソース ライブラリや内部アルゴリズムを使用しているという主張はなく、またこの例が製品パフォーマンス テストに代わるものでもありません。

📊 コアの比較

🎯 どの方法があなたに適していますか?

もしあなたが……

• ドキュメントには多くのコードとコマンドがあります: セマンティック タグを使用してコード ノードを識別し、最初にシールドしてから翻訳することを優先します。
• コード ブロックの構造は複雑で深くネストされています: .string を読み取るだけでなく、get_text() または再帰的走査を使用してください。
• このページはカスタム コード コンテナを使用しています: クラスのホワイトリストを確立し、受け入れ中にヒット率を確認します。
• 正式な配信の準備: 自動検証と手動レビューを同時に実行します。スクリプトが正常に実行されるかどうかだけを見てはいけません。

❓ よくある質問 (FAQ)

1. コードを正規表現に置き換えることができないのはなぜですか?

HTML はネストされたツリー構造であり、正規表現では <code>、<span>、および <a> 間のネストされた関係を理解することが難しく、ラベルを閉じるエラーや境界の欠落が容易に発生する可能性があります。

2. コードブロック内のコメントは翻訳する必要がありますか?

承認フォームでは、コード ブロック内のコメントがスキップされているかどうかを確認することを推奨しています。コメントに重要なビジネス ロジックの説明が含まれている場合は、個別に抽出して翻訳する必要があります。

3. スクリプトの実行時にエラーが発生しない場合は、コード保護に問題がないことを意味しますか?

できません。 DOM 構造を比較し、主要な属性が変更されているかどうかを確認し、プレースホルダーの数を確認し、手動でレビューすることも必要です。

4. この方法はすべての文書に適用されますか?

いいえ。マークダウン レンダリングによって生成された純粋な div + span コード ブロック、または圧縮された単一行 HTML の場合、パーサーはコード境界を正しく識別できない可能性があるため、最初にフォーマットするか、手動処理に引き渡す必要があります。

📝 概要

技術文書翻訳の鍵は、翻訳前に DOM ツリーを使用してコードと自然言語を分離し、受け入れチェックリストを使用して結果を確認することです。まず合成サンプルでルールを検証し、次に感度を下げた本物の文書で再確認します。

今すぐ試してみましょう: ドキュメントをアップロードして、元のレイアウトを保持したまま翻訳を開始します