WordPress .po 파일에서 퍼지(Fuzzy) 번역을 수정하는 방법

모든 문자열을 번역했습니다. 파일을 저장하고, .mo 파일을 업로드하고, 사이트를 새로고침했습니다. 하지만 여전히 일부 레이블은 고집스럽게 영어로 남아 있습니다. .po 파일을 열어 해당 문자열을 찾아보면, 완벽하게 번역되어 있습니다. 그런데 왜 WordPress는 이를 무시할까요?

그 답은 거의 항상 항목 위에 숨어 있는 작은 플래그입니다: #, fuzzy. **퍼지 번역(fuzzy translation)**은 gettext가 "이 번역은 틀렸을 수도 있으니 아직 신뢰하지 마세요"라고 말하는 방식입니다. 그리고 결정적으로, WordPress는 라이브 사이트에서 퍼지 문자열을 표시하기를 거부하고 대신 원래 영어로 되돌아갑니다. 이것은 "내 번역이 표시되지 않습니다" 문제의 가장 흔한 오해 중 하나입니다.

이 가이드는 퍼지 번역(fuzzy translation) 플래그가 정확히 무엇을 의미하는지, 왜 카탈로그에 계속 나타나는지, 그리고 Poedit, 명령줄 및 전체 백로그에 걸쳐 대규모로 퍼지 문자열을 찾고 지우는 방법을 설명합니다. 메커니즘을 이해하면 누락된 번역의 미스터리가 사라질 것입니다.

퍼지 플래그는 실제로 무엇을 의미하나요?

퍼지 플래그는 gettext가 번역 항목에 추가하여 해당 번역이 불확실하고 사람의 검토가 필요함을 나타내는 마커입니다. 원시 .po 파일에서는 문자열 바로 위에 특별한 주석으로 나타납니다.

#: includes/cart.php:88
#, fuzzy
msgid "Add to cart"
msgstr "Im Warenkorb"

그 #, fuzzy 줄은 WordPress를 포함하여 gettext를 인식하는 모든 도구에 해당 msgstr이 임시적임을 알려줍니다. 번역은 존재하지만 gettext는 이를 확정된 것으로 간주하지 않습니다.

WordPress가 퍼지 문자열을 건너뛰는 이유

여기에 모든 사람을 당황하게 하는 동작이 있습니다. WordPress가 .mo 파일을 컴파일하거나 읽을 때, 퍼지 항목을 번역되지 않은 것으로 간주합니다. 문자열은 기술적으로 파일에 존재하지만, WordPress는 의도적으로 이를 무시하고 원래 msgid를 표시합니다.

따라서 사용자 입장에서는 번역이 "완료"되었고, 파일에 그대로 있습니다. 하지만 WordPress 입장에서는 해당 문자열에 신뢰할 수 있는 번역이 없으므로 영어 원본을 렌더링합니다. 이것이 바로 완성된 것처럼 보이는 카탈로그가 여전히 프런트엔드에서 번역되지 않은 텍스트를 표시할 수 있는 이유입니다.

이러한 설계는 의도적이며, 솔직히 말해 합리적입니다. 퍼지 플래그의 핵심은 검증되지 않은, 잠재적으로 잘못된 번역이 조용히 배포되는 것을 방지하는 것입니다. 예를 들어, 원래 "Delete account"였던 문자열이 나중에 "Deactivate account"로 변경되었다고 상상해 보세요. gettext가 이전 번역을 맹목적으로 유지한다면, 사용자는 실제로는 비활성화만 하는 "Delete account"라는 레이블의 버튼을 볼 수 있으며, 이는 위험한 불일치입니다. 퍼지 문자열을 숨김으로써 gettext는 번역이 새로운 의미와 일치하는지 사람이 확인하도록 강제합니다. 이 플래그는 안전 장치이며 버그가 아닙니다.

퍼지 플래그가 계속 나타나는 이유는 무엇인가요?

퍼지 플래그는 무작위로 생성되지 않습니다. 이는 gettext 도구에 의해 주로 두 가지 상황에서 자동으로 생성되며, 이 두 가지를 이해하면 이를 방지하는 방법을 알 수 있습니다.

원본 문자열이 변경된 경우

가장 흔한 원인은 원본 업데이트입니다. 개발자가 다음 플러그인 버전에서 문자열을 "Add to cart"에서 "Add to basket"으로 변경했다고 상상해 보세요. 새로운 템플릿을 기존 번역에 병합할 때, gettext는 원본이 원래 번역했던 내용과 더 이상 일치하지 않음을 감지합니다. 이전 번역을 버리는 대신, gettext는 이를 유지하지만 퍼지로 표시하여 본질적으로: "영어가 변경되었으므로 번역이 여전히 맞는지 다시 확인해 주세요"라고 말합니다.

번역 메모리 및 msgmerge에 의한 자동 매칭

두 번째 원인은 병합 중 퍼지 매칭입니다. msgmerge 도구는 새 템플릿에 대해 이전 번역 파일을 업데이트하며, 이전 문자열과 유사하지만 동일하지 않은 원본 문자열을 찾으면 이전 번역을 복사하고 퍼지로 플래그를 지정합니다.

# Merge a new template into an existing translation.
# Similar-but-changed strings get marked #, fuzzy automatically.
msgmerge --update awesome-plugin-de_DE.po awesome-plugin.pot

데스크톱 편집기의 번역 메모리(Translation Memory)도 동일하게 작동합니다: 유사한 일치 항목에서 제안을 자동으로 채울 때, 결과를 퍼지로 표시하여 사용자가 이를 확인하도록 합니다. 두 경우 모두 플래그는 제 역할을 하고 있습니다. 문제는 퍼지 항목이 검토되지 않은 채 남아 있고, WordPress가 조용히 이를 숨긴다는 점뿐입니다.

알아둘 만한 세 번째, 더 교묘한 원인이 있습니다: 복사-붙여넣기 및 대량 가져오기 도구입니다. 일부 번역 플랫폼과 가져오기 스크립트는 보수적인 조치로 기본적으로 모든 항목을 퍼지로 표시하여, 나중에 사람이 각 항목을 확인하도록 예상합니다. 다른 시스템에서 카탈로그를 가져왔는데 모든 문자열이 갑자기 퍼지로 표시된다면, 대개 이것이 이유입니다. 번역은 완벽할 수 있지만, 플래그가 지워지기 전까지는 어떤 것도 사이트에 나타나지 않을 것입니다. 플래그의 출처를 알면 각 항목을 실제로 검토해야 하는지, 아니면 안심하고 일괄적으로 지워도 되는지 알 수 있습니다.

퍼지 문자열을 찾고 수정하는 방법은?

퍼지 문자열을 지우는 것은 각 문자열을 검토하고, 번역이 올바르다고 확인되면 플래그를 제거하는 것을 의미합니다. 작업의 규모에 따라 이를 수행하는 세 가지 실용적인 방법이 있습니다.

Poedit에서 퍼지 문자열 수정하기

Poedit은 이 작업을 가장 쉽게 만듭니다. .po 파일을 열고 검색 및 필터 컨트롤을 사용하여 퍼지 항목만 표시합니다. 이들은 색상으로 구분되어 (일반적으로 주황색) 즉시 눈에 뜁니다. 각 항목을 클릭하여 번역을 확인하거나 수정한 다음, 키보드 단축키 (편집 > "번역이 퍼지 상태" 또는 메뉴에 표시된 단축키)로 퍼지 상태를 해제합니다. 저장하면 Poedit은 깔끔한 .mo를 다시 컴파일하고, 이제 확인된 문자열이 사이트에 표시될 것입니다. 이 편집기가 처음이라면, Poedit 완전 가이드에서 필터 및 검토 워크플로를 자세히 다룹니다.

명령줄에서 퍼지 문자열 수정하기

자동화 또는 대규모 카탈로그의 경우 명령줄이 더 빠릅니다. 퍼지 항목의 수를 세고, 대량으로 확인한 후 플래그를 제거하여 WordPress가 이를 로드하도록 할 수 있습니다.

# Count how many fuzzy strings remain
msgattrib --only-fuzzy --no-obsolete awesome-plugin-de_DE.po | grep -c "msgid"

# Clear all fuzzy flags (only after you trust the translations)
msgattrib --clear-fuzzy --empty awesome-plugin-de_DE.po \
  --output-file=awesome-plugin-de_DE.po

대량으로 지울 때는 주의하십시오. 번역을 검토하지 않고 퍼지 플래그를 제거하는 것은 플래그의 목적을 무효화하고 실제로 잘못된 텍스트를 사용자에게 제공할 수 있습니다. 번역 소스를 신뢰할 때 명령줄 방식을 사용하고, 신뢰하지 않을 때는 수동 Poedit 방식을 사용하십시오.

안전한 중간 방법은 퍼지 문자열을 별도의 파일로 내보내어 해당 문자열만 검토한 다음 다시 병합하는 것입니다. 이렇게 하면 실제로 주의가 필요한 항목에만 집중하면서 확인된 번역은 그대로 유지됩니다.

# Extract only the fuzzy entries for focused review
msgattrib --only-fuzzy --no-obsolete awesome-plugin-de_DE.po \
  --output-file=fuzzy-only.po

고립된 50개의 문자열을 검토하는 것이 수천 줄짜리 카탈로그에서 주황색 행을 찾아 스크롤하는 것보다 오류 발생 가능성이 훨씬 적으며, 마지막 업데이트에서 정확히 무엇이 변경되었는지 깔끔하게 기록할 수 있습니다.

플래그를 지운 후에는 항상 .mo 파일을 다시 저장하거나 다시 컴파일하십시오. 퍼지 상태는 .po 파일에 있지만, WordPress는 이진 .mo 파일을 읽으므로, 이를 다시 생성할 때까지 .po 파일이 깔끔해 보여도 프런트엔드에는 계속 영어가 표시될 것입니다. Poedit은 저장 시 자동으로 다시 컴파일합니다. 명령줄에서는 msgfmt awesome-plugin-de_DE.po -o awesome-plugin-de_DE.mo를 실행합니다. 이 마지막 컴파일 단계를 잊는 것은 새로 퍼지 상태가 제거된 카탈로그가 여전히 나타나지 않는 가장 흔한 이유 중 하나입니다. 번역은 원본 파일에서 확인되었지만, 사이트가 실제로 로드하는 이진 파일은 오래된 것입니다.

퍼지 항목은 종종 복수형 문자열과 함께 나타나는데, 여기서 변경된 msgid_plural이 전체 복수형 블록을 퍼지로 표시할 수 있습니다. 퍼지 백로그에 개수와 수량 관련 내용이 많다면, Gettext 복수형 및 복잡한 복수화에 대한 저희 가이드에서 병합 중 이러한 항목이 특히 취약한 이유를 설명합니다.

대규모 퍼지 백로그 지우기

단일 퍼지 문자열은 30초면 수정할 수 있습니다. 주요 플러그인 업데이트 후 400개의 퍼지 문자열을 가진 카탈로그는 다른 문제이며, 수십 개의 언어에 걸쳐 있으면 진정한 병목 현상이 됩니다. 검토 없이 플래그를 대량으로 지우려는 유혹은 바로 잘못된 번역이 프로덕션 환경에 도달하는 방식입니다.

더 깔끔한 해결책은 오래된 일치 항목을 무작정 승인하는 대신 퍼지 항목을 새로 번역하는 것입니다. SimplePoTranslate를 통해 카탈로그를 실행하면, 컨텍스트 인식 AI가 변경된 모든 문자열에 대해 현재의 확정된 번역을 생성하므로, 경고 플래그만 제거하는 것이 아니라 불확실한 일치 항목을 실제 번역으로 대체하게 됩니다. **구문 잠금(Syntax Locking)**은 %s, %1$s, {count} 및 HTML 태그를 모두 그대로 유지하며, **스마트 배치(Smart Batching)**는 업데이트 후의 대규모 카탈로그를 한 번에 처리합니다. .po, .mo, .json, .php, .xliff 파일이 포함된 깔끔한 ZIP 파일을 받게 되며, 퍼지 백로그가 남아있지 않아 클라우드에서 바로 배포할 수 있습니다.

이것을 번역이 전혀 표시되지 않는 더 광범위한 문제와 구별하는 것이 중요합니다. 퍼지 플래그는 하나의 특정 원인이지만, .mo 파일 누락, 잘못된 파일 이름, 로케일 불일치도 동일한 증상을 유발합니다. 전체 진단 체크리스트는 WordPress에서 번역이 표시되지 않는 문제 해결 가이드를 참조하십시오. 이 가이드에서는 퍼지 문자열을 더 큰 목록의 한 항목으로 다룹니다.

전체 퍼지 백로그를 지우고 모든 문자열이 사이트에 표시되도록 할 준비가 되셨나요? SimplePoTranslate를 무료로 사용해 보세요 — 신용카드는 필요 없습니다. 무료 플랜은 .po 파일을 새로 번역하여, 불확실한 퍼지 일치 항목을 깔끔하고 확정된 번역으로 대체합니다.