단어 하이퍼링크는 보이는 텍스트를 변경할 수 있을 뿐만 아니라 대상을 확인할 수도 있습니다.

이 문서는 Word 문서 번역이나 콘텐츠 정리를 수행하는 개발자를 위해 작성되었습니다. 많은 사람들이 스크립트를 사용하여 하이퍼링크 텍스트를 바꾼 후 응답이 없거나 클릭하면 오류 페이지로 이동합니다. 문제가 무엇인지, python-docx로 보이는 텍스트를 안전하게 수정하는 방법, 전달 전 확인해야 할 경계는 무엇인지 알려드립니다.

이 기사에서는 합성 샘플을 사용하여 처리 방법을 보여줍니다. 코드는 격리된 환경에서 예제를 통해 확인되었습니다. 이는 모든 실제 파일이나 제품 성능을 보장하지 않습니다. 중요한 서류를 처리하기 전, 원본을 보관하시고, 본문에 기재된 경계 및 허용 항목에 따라 검토하시기 바랍니다.

Word에서 하이퍼링크 텍스트를 안전하게 바꾸는 방법은 무엇입니까? 한 문장 결론

하이퍼링크의 보이는 텍스트만 교체하고 하이퍼링크 개체를 통해 해당 하위 실행을 하나씩 작동합니다. 전체 단락의 text 속성에 값을 할당하지 마십시오. 그렇지 않으면 URL 관계가 손실됩니다.

당신의 상황	권장 사례	이유
일반 외부 링크, 텍스트는 단일 실행으로 구성됩니다.	`iter_inner_content()`를 사용하여 하이퍼링크를 찾아 지우고 새 텍스트를 작성하세요.	`<w:hyperlink>` 컨테이너와 `r:id` 간의 관계를 유지하고 URL은 변경되지 않습니다.
하이퍼링크 텍스트에는 다양한 형식의 여러 실행이 포함되어 있습니다.	먼저 모든 하위 실행을 지운 다음 새 실행을 작성하세요.	`runs[0]`만 교체하여 잔여 텍스트가 발생하지 않도록 하세요.
내부 책갈피를 문서화하기 위한 목차 또는 상호 참조 지점	`fragment`를 유지하고 대상을 수정하지 마십시오.	이러한 유형의 링크의 `address`는 비어 있으며 강제 확인 또는 URL 스플라이싱으로 인해 우발적인 손상이 발생할 수 있습니다.
하이퍼링크는 페이지 나누기에 걸쳐 있거나 콘텐츠 컨트롤 또는 필드 내에 중첩되어 있습니다.	직접 검토용으로 표시	구조는 취약하며 python-docx는 복잡한 필드에 대한 지원이 제한되어 있습니다.

하이퍼링크 텍스트를 클릭해도 점프하지 못하는 이유는 무엇입니까?

Word 문서 번역 또는 콘텐츠 정리를 처리할 때 자주 발생하는 오류는 다음과 같습니다. 스크립트가 "여기를 클릭"을 "여기를 클릭"으로 성공적으로 바꾸었지만 사용자가 새 텍스트를 클릭하면 응답하지 않거나 오류 페이지로 이동합니다. 근본적인 이유는 python-docx의 Paragraph.text가 읽고 쓸 수 있지만 할당 동작이 파괴적이라는 것입니다. 읽을 때 라이브러리는 하이퍼링크의 일반 텍스트와 표시되는 텍스트를 문자열로 연결합니다. 할당할 때 실제로 전체 단락을 새로운 일반 텍스트 실행으로 덮고 <w:hyperlink>에 원래 캡슐화된 URL 관계(관계)는 삭제됩니다.

OpenXML에서 하이퍼링크는 단순한 텍스트 속성이 아니라 여러 실행을 포함하는 구조화된 컨테이너입니다. 하이퍼링크를 안전하게 수정하려면 단락 수준 텍스트 작업을 우회하고 Hyperlink 개체 내부로 깊이 이동하여 외부 컨테이너를 그대로 유지하면서 해당 자식 Run의 텍스트를 정확하게 바꿔야 합니다. 이는 코드 정확성에 관한 것일 뿐만 아니라 문서 번역에서 "데드 링크"를 피하기 위한 기본 요구 사항이기도 합니다.

합성 예: 올바른 출력 및 경계 트랩

문제를 설명하기 위해 실제 고객 데이터 없이 합성 시나리오를 구성합니다. 입력 문서에 "자세한 내용은 공식 문서를 참조하세요."라는 텍스트가 있다고 가정합니다.

올바른 출력이 예상됩니다: 처리 후에도 단락 XML의 <w:hyperlink> 노드가 여전히 존재하고 r:id가 가리키는 관계 ID는 변경되지 않고 해당 URL은 여전히 https://example.com/docs입니다. 노드 내부의 <w:t> 내용만 "공식 문서(중국어)"가 되며, 나머지 단락의 형식과 내용은 영향을 받지 않습니다.

일반적인 오류 및 경계 입력:

직접 할당 대체: paragraph.text = paragraph.text.replace('官方文档', '官方文档（中文）')를 실행합니다. 하이퍼링크가 사라지고 전체 단락이 일반 텍스트가 되며 URL이 영구적으로 손실됩니다.
다중 실행 하이퍼링크: "공식 문서"라는 네 단어 중 "공식"이 굵게 표시되고 "문서"가 일반 스타일인 경우 Word에서는 이를 두 개의 실행으로 분할합니다. 코드에서 hyperlink.runs[0]가 모두 텍스트라고 가정하고 전체적으로 대체하면 두 번째 실행은 그대로 유지되고 결국 "공식 문서(중국어) 문서"로 표시됩니다.
내부 북마크 링크: 목차의 하이퍼링크에는 HTTP 주소가 없는 경우가 많지만 문서 내부의 _Toc 북마크를 가리킵니다. 이때 address는 비어 있으며 책갈피 참조는 fragment 속성에 저장됩니다. 코드가 강제로 http 접두사를 확인하거나 URL을 연결하려고 시도하는 경우 이러한 합법적인 링크는 비정상적이거나 잘못 수정된 것으로 잘못 판단됩니다.

하이퍼링크 텍스트를 안전하게 대체하기 위한 코드 구현

다음 예에서는 링크 구조를 깨지 않고 표시되는 텍스트를 업데이트하는 방법을 보여줍니다. 이 코드는 논리 데모일 뿐입니다. 종속성을 잠그는 자체 환경에서 실행하세요. 사용하기 전에 하나 이상의 외부 하이퍼링크를 입력으로 포함하는 input.docx를 준비하십시오. 예를 들어 Word에서 https://example.com/docs에 "공식 문서" 링크를 수동으로 삽입하십시오.

# 依赖: python-docx 1.2 系列（本次运行环境见 QA 清单） (Hyperlink 对象支持)
# 注意: 本示例不验证网络请求，仅在内存中操作文档结构
from docx import Document
from docx.text.hyperlink import Hyperlink

def translate_hyperlink_text(doc_path, source_text, target_text):
    """
    安全替换超链接可见文本，保留原始URL目标。
    仅当超链接完整文本精确匹配source_text时替换。
    """
    doc = Document(doc_path)
    replaced_count = 0

    for para in doc.paragraphs:
        # 必须使用 iter_inner_content 而非 runs，以捕获超链接对象
        for item in para.iter_inner_content():
            # 显式类型检查，确保是Hyperlink对象
            if isinstance(item, Hyperlink):
                # 精确匹配完整超链接文本，避免部分匹配导致结构损坏
                if item.text == source_text:
                    # 清空所有子Run的文本，防止多Run残留
                    for run in item.runs:
                        run.text = ""
                    # 将译文写入第一个Run，保留其原有格式
                    if item.runs:
                        item.runs[0].text = target_text
                        replaced_count += 1
                    else:
                        # 防御性处理：空超链接容器
                        print(f"警告: 发现无Run的超链接容器，跳过")

    assert replaced_count > 0, "未找到匹配的超链接，请检查源文本"
    return doc

# 使用示例（需读者自备 input.docx）:
# new_doc = translate_hyperlink_text("input.docx", "官方文档", "Official Docs")
# new_doc.save("output.docx")

이 코드의 핵심은 iter_inner_content()를 사용하여 단락 콘텐츠를 탐색하는 것입니다. 그러면 runs 속성과 같은 하이퍼링크 컨테이너를 무시하는 대신 문서 순서대로 실행 및 하이퍼링크 개체가 생성됩니다. 대체 전략은 하이퍼링크가 서로 다른 형식의 여러 실행으로 구성되더라도 텍스트 잔여물이 없도록 "먼저 지우고 쓰기"를 채택합니다. 어설션 문은 자동 오류를 방지하기 위해 자동화된 프로세스에서 "누락" 문제를 신속하게 노출하는 데 사용됩니다.

📊 핵심 비교

관행	결과	주요 리스크
`paragraph.text`에 값 할당	하이퍼링크가 사라지고 전체 단락이 일반 텍스트가 됩니다.	URL이 영구적으로 손실됨
`hyperlink.runs[0]`만 교체	텍스트가 남아 있을 수 있습니다.	다중 실행 하이퍼링크 표시 오류
하이퍼링크로 실행해서 클리어 후 쓰기	하이퍼링크 컨테이너 및 관계 ID 유지	줄 바꿈, 책갈피, 페이지 교차 등의 경계를 추가로 허용해야 합니다.

허용 기준 및 직접 검토 경계

코드 데모는 엔드투엔드 성능과 동일하지 않습니다. 배송 전, 다음 표의 승인 여부를 확인하고 어떤 상황을 수동 처리에 넘겨야 하는지 명확히 해야 합니다.

현상 관찰	처리 결정	주목
교체 후 링크는 정상적으로 원래 URL로 이동할 수 있습니다.	통과하다	기본 기능 수용
하이퍼링크 텍스트에 줄 바꿈이나 탭이 포함되어 있습니다.	코드 데모에서는 일반 텍스트만 처리하며 특수 문자 매핑은 유지되어야 합니다.	공식 문서에서 줄바꿈과 탭의 매핑 방법을 확인해야 합니다.
하이퍼링크는 문서 내부의 책갈피를 가리킵니다(주소가 비어 있음).	조각을 유지하고 대상을 수정하지 마십시오	디렉토리와 상호 참조가 이 범주에 속하며 url 속성은 빈 문자열을 반환합니다.
하이퍼링크는 페이지 나누기에 걸쳐 있습니다.	직접 검토용으로 표시	Contains_page_break=True인 경우 구조가 취약합니다.
동일한 URL은 여러 개의 서로 다른 표시 텍스트에 해당합니다.	상황에 따라 별도 처리, 일괄 교체 금지	용어의 일관성은 용어집과 함께 판단해야 합니다.
콘텐츠 제어 또는 필드에 중첩된 하이퍼링크	수동 처리로 전환	python-docx는 복잡한 필드에 대한 지원이 제한되어 있습니다.

특히 이 시나리오는 편지 병합 필드, SmartArt 내의 링크 또는 보호된 문서 영역에서는 작동하지 않습니다. 이러한 시나리오의 XML 구조는 고도로 전문화되어 있으며 범용 구문 분석기는 되돌릴 수 없는 손상을 일으킬 수 있습니다. 이러한 파일이 발견되면 전처리 단계에서 표시하고 제외해야 합니다.

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

일반적인 외부링크를 다루는 경우

Run by Run을 교체하기 위해 Hyperlink 개체를 사용하고 교체 후에도 r:id 및 URL이 변경되지 않은 상태로 유지되는지 확인합니다.

목차나 상호 참조를 다루는 경우

fragment를 유지하고 http 접두사를 확인하지 않으며 책갈피 대상을 수정하지 마십시오.

하이퍼링크 텍스트에 여러 형식이 포함된 경우

먼저 모든 하위 실행을 지운 다음 새 실행을 작성하고 첫 번째 실행에서 대체된 스타일을 가져옴을 나타냅니다.

링크가 페이지 나누기, 콘텐츠 제어, 필드, SmartArt 또는 보호 영역에 있는 경우

수동 처리로 직접 전환하고 일반 스크립트를 사용하여 일괄 다시 작성하지 마십시오.

자체 포함된 하이퍼링크 샘플

다음은 OOXML 관계만 구성하고 외부 URL에 액세스하지 않습니다. 대체된 스타일은 첫 번째 실행에서 나옵니다. 원본 링크에 여러 스타일이 있는 경우 별도의 세그먼트 매핑을 정의해야 하며 이는 모든 혼합 형식의 무손실 보존으로 간주될 수 없습니다.

from io import BytesIO
from docx.oxml import OxmlElement
from docx.oxml.ns import qn
from docx.opc.constants import RELATIONSHIP_TYPE as RT
source = Document()
p = source.add_paragraph()
link = OxmlElement("w:hyperlink")
rid = p.part.relate_to("https://example.com/", RT.HYPERLINK, is_external=True)
link.set(qn("r:id"), rid)
run = OxmlElement("w:r")
text = OxmlElement("w:t")
text.text = "Docs"
run.append(text)
link.append(run)
p._p.append(link)
stream = BytesIO()
source.save(stream)
stream.seek(0)
changed = translate_hyperlink_text(stream, "Docs", "Documentation")
found = list(changed.paragraphs[0].hyperlinks)
assert found[0].text == "Documentation"
assert found[0].address == "https://example.com/"

참조 및 다음 단계

python-docx 하이퍼링크 API 문서: https://python-docx.readthedocs.io/en/latest/api/text.html#Hyperlink
python-docx Paragraph.iter_inner_content 설명: https://python-docx.readthedocs.io/en/latest/api/text.html#docx.text.paragraph.Paragraph.iter_inner_content

문서 번역에 이 체크리스트를 사용하세요

단어 번역에서는 내용 문제와 형식 문제가 혼합되는 경향이 있습니다. 스타일, 헤더, 표 등의 확인 항목을 배송 목록에 추가하면 리뷰어가 어디를 봐야 할지 알 수 있습니다.

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

❓ 자주 묻는 질문(FAQ)

1. 하이퍼링크 텍스트를 대체하기 위해 단락 텍스트에 직접 값을 할당할 수 없는 이유는 무엇입니까?

할당이 전체 단락을 일반 텍스트 실행으로 덮어쓰므로 하이퍼링크 컨테이너와 그 안에 포함된 URL 관계가 삭제되고 링크가 사라집니다.

2. 하이퍼링크가 여러 Run으로 구성된 경우 첫 번째 Run만 교체하면 어떻게 되나요?

두 번째 및 후속 실행은 그대로 유지되며 결국 "공식 문서(중국어) 문서"와 같은 반복 텍스트로 나타날 수 있습니다.

3. 디렉토리의 하이퍼링크 URL이 비어 있는 이유는 무엇입니까?

목차 링크는 일반적으로 HTTP 주소가 없는 문서 내부의 _Toc 책갈피를 가리킵니다. 책갈피 참조는 fragment 속성에 저장되며 수정하기보다는 보존해야 합니다.

4. 어떤 하이퍼링크를 수동 처리에 맡겨야 합니까?

페이지 나누기에 걸쳐 있는 링크, 콘텐츠 컨트롤 또는 필드 내에 중첩된 링크, 편지 병합 필드, SmartArt 또는 보호된 영역 내의 링크는 모두 수동으로 처리해야 합니다.

📝 요약

하이퍼링크 텍스트 교체의 핵심은 전체 구간을 할당하는 것이 아닌 하이퍼링크 객체 내부에서 Run을 조작하고, 전달 전에 경계 조건을 하나씩 수용하는 것입니다. 실제 문서를 다룰 때는 원본을 먼저 보관한 후 감도가 낮은 샘플로 확인하십시오.

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