기술 문서 번역은 코드 번역이 가장 두렵습니다. 코드 블록을 보호하려면 Beautiful Soup을 사용하세요.

기술 문서 번역 시 user_id를 "사용자 식별자"로 번역하거나 <div class="container">의 클래스 속성을 변경하는 것은 비용이 많이 들고 문제 해결이 어렵습니다. 이러한 유형의 오류는 일반적으로 프로그램을 중단시키지 않지만 복사하여 붙여넣은 코드가 오류를 직접 보고하거나 API 문서의 예제를 유효하지 않게 만들 수 있습니다.

해결책은 번역 엔진이 얼마나 스마트한가가 아니라 전처리 단계에서 DOM 트리의 자연어와 코드를 정확하게 분리할 수 있는지 여부에 있습니다. 다음은 먼저 정규식만으로는 충분하지 않은 이유를 설명한 다음 합성 샘플을 사용하여 뷰티플수프의 노드 식별 방법을 시연하고 마지막으로 허용 기준을 제공합니다. 모든 예시는 합성 데이터이므로 중요한 파일을 작업하기 전에 원본을 보관하시기 바랍니다.

기술문서 번역 시 코드를 보호하는 방법은 무엇인가요? 한 문장 결론

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에 있으므로 없음을 얻게 됩니다. 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에만 적용됩니다. 의미 체계 태그가 없는 Markdown 렌더링으로 생성된 순수 <div> + <span> 코드 블록 또는 HTML의 난독화되고 압축된 단일 행의 경우 파서가 코드 경계를 올바르게 식별하지 못할 수 있습니다. 이러한 문서는 먼저 형식을 지정하고 정리하거나 수동 처리에 직접 넘겨야 합니다. 또한, 이 검증은 "코드가 번역되지 않는다"는 것만 보장할 뿐, 번역의 자연어 품질을 보장하지는 않습니다.

체크리스트를 실제 문서에 적용

웹 문서의 텍스트, 링크, 코드 및 구조는 별도로 처리되어야 합니다. 보호된 부분을 승인 목록에 추가한 후 번역 후 가독성 및 페이지 표시 효과를 평가합니다.

OmniDoc(제품 포털)는 다양한 형식의 문서 번역 포털을 제공하며 공식 웹사이트에서는 OCR, 용어집 및 이중 언어 비교 기능을 소개합니다. 파일에서 직접 작업을 시작하려는 팀의 경우 이는 실제 샘플을 통해 평가할 가치가 있는 경로입니다. 업로드 권한이 있는 둔감화된 파일을 사용하시고, 이 글의 확인 항목을 사용하여 결과를 검토하시기 바랍니다. OmniDoc이 이 기사에 언급된 오픈 소스 라이브러리나 내부 알고리즘을 사용한다는 주장은 없으며 이 예가 제품 성능 테스트를 대체하지도 않습니다.

📊 핵심 비교

🎯 어떤 방법이 당신에게 적합합니까?

만약 당신이…

• 문서에 코드와 명령어가 많습니다. 코드 노드를 식별하기 위해 의미론적 태그를 우선적으로 사용하고, 먼저 보호한 다음 번역합니다.
• 코드 블록 구조가 복잡하고 깊게 중첩되어 있습니다. get_text() 또는 재귀 순회를 사용하고, .string만 읽지 마세요.
• 이 페이지는 사용자 정의 코드 컨테이너를 사용합니다. 수업에 대한 화이트리스트를 설정하고 수락 시 적중률을 확인합니다.
• 정식 배송 준비: 자동 검증과 수동 검토를 동시에 수행합니다. 스크립트가 성공적으로 실행되는지 여부만 보지 마십시오.

❓ 자주 묻는 질문(FAQ)

1. 코드를 정규식으로 바꿀 수 없는 이유는 무엇인가요?

HTML은 중첩된 트리 구조이므로 정규식이 <code>, <span> 및 <a> 간의 중첩 관계를 이해하기 어렵습니다. 이로 인해 레이블 닫기 오류나 경계 누락이 쉽게 발생할 수 있습니다.

2. 코드 블록의 주석을 번역해야 합니까?

수락 양식에서는 코드 블록 내의 주석을 건너뛰는지 확인하도록 권장합니다. 주석에 중요한 비즈니스 논리 설명이 포함되어 있는 경우 별도로 추출한 다음 번역해야 합니다.

3. 스크립트 실행 시 오류가 없다면 코드 보호에 문제가 없다는 뜻인가요?

할 수 없습니다. DOM 구조를 비교하고, 주요 속성이 변경되었는지 확인하고, 자리 표시자 수를 확인하고, 수동 검토를 수행하는 것도 필요합니다.

4. 이 방법은 모든 문서에 적용되나요?

아니요. 마크다운 렌더링으로 생성된 순수 div + span 코드 블록 또는 압축된 단일 행 HTML의 경우 파서가 코드 경계를 올바르게 식별하지 못할 수 있으며 먼저 형식을 지정하거나 수동 처리로 넘겨야 합니다.

📝 요약

기술 문서 번역의 핵심은 번역 전 DOM 트리를 이용해 코드와 자연어를 분리하고, 승인 체크리스트를 이용해 결과를 확인하는 것이다. 먼저 합성 샘플에 대한 규칙을 확인한 다음 둔감한 실제 문서로 다시 확인하세요.

지금 사용해 보세요: 원본 레이아웃을 유지하면서 번역을 시작하려면 문서를 업로드하세요.