.po vs .mo vs .pot: WordPress 번역 파일 설명
WordPress 테마의 languages 폴더를 열면 twentytwentyfour.pot, twentytwentyfour-de_DE.po, twentytwentyfour-de_DE.mo와 같이 거의 동일하게 보이는 세 개의 파일을 발견합니다. 같은 테마, 같은 언어이지만 세 개의 다른 확장자입니다. 어떤 파일을 편집해야 할까요? WordPress는 실제로 어떤 파일을 로드할까요? 그리고 잘못된 파일을 편집하면 번역이 소리 없이 사라지는 이유는 무엇일까요?
po vs mo 파일 논쟁에서 어떤 파일이 중요한지 궁금해 본 적이 있다면, 당신 혼자만이 아닙니다. 이 세 가지 확장자는 모든 번역된 WordPress 사이트의 근간을 이루지만, 그 차이점은 초보자와 숙련된 개발자 모두를 혼란스럽게 만듭니다. 잘못된 파일을 편집하면 독일 방문자는 여전히 영어를 보게 됩니다. 올바른 파일을 편집했지만 단계를 건너뛰면 아무것도 변경되지 않습니다.
이 가이드는 .pot, .po, .mo 파일이 정확히 무엇인지, GNU Gettext 워크플로우 내에서 어떻게 관련되는지, WordPress에서 어디에 저장되는지, 그리고 .mo 파일을 텍스트 편집기에서 열어서는 안 되는 이유를 설명합니다. 이 가이드를 마치면 어떤 파일을 수정하고 어떤 파일은 그대로 두어야 하는지 알게 될 것입니다.
.pot, .po, .mo 파일은 무엇인가요?
간단히 말해: .pot 파일은 빈 템플릿이고, .po 파일은 편집 가능한 번역 파일이며, .mo 파일은 WordPress가 런타임 시 읽는 컴파일된 바이너리입니다. 이들은 사슬을 이루며, 각 링크는 정확히 하나의 역할을 합니다.
이 세 가지 형식은 모두 WordPress, Drupal, 그리고 수많은 PHP 및 C 프로젝트가 의존하는 지역화 시스템인 GNU Gettext에서 유래합니다. Gettext는 개발자가 작성하는 원본 문자열과 번역가가 제공하는 번역을 분리하여, 동일한 코드베이스가 단 한 줄의 PHP 코드도 건드리지 않고 수십 가지 언어를 구사할 수 있도록 합니다.
레시피 카드와 같다고 생각해보세요. .pot은 재료 칸은 있지만 수량은 없는 빈 카드입니다. .po는 특정 요리를 위해 채워진 카드입니다. .mo는 주방에서 실제로 서비스 중에 사용하는 코팅되어 기계로 스캔 가능한 사본입니다. 종이 카드에 직접 쓰지만, 코팅된 카드에는 절대 낙서하지 않습니다.
.pot 파일: 마스터 템플릿
.pot 파일(Portable Object Template)은 테마 또는 플러그인에 있는 모든 번역 가능한 문자열을 포함하며, 번역 내용은 비어 있습니다. 이것은 개발자가 배포하는 마스터 목록으로, 번역가들이 무엇을 번역해야 할지 정확히 알 수 있도록 합니다. msgstr 라인은 아직 언어가 선택되지 않았기 때문에 비어 있습니다.
#: includes/checkout.php:42
msgid "Add to Cart"
msgstr ""
#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr ""
비어 있는 msgstr ""에 주목하세요. .pot은 번역이 아닌 템플릿입니다. 언어별로 한 번 복사하여 빈칸을 채웁니다. .pot 파일을 수동으로 편집하는 경우는 드뭅니다. 문자열이 변경될 때마다 소스 코드에서 재생성됩니다.
.po 파일: 사람이 편집 가능한 번역 파일
.po 파일(Portable Object)은 .pot 파일의 사본으로, 하나의 언어에 맞게 msgstr 라인이 채워져 있습니다. 이것은 번역가와 개발자가 실제로 편집하는 파일입니다. 일반 텍스트이며, 사람이 읽을 수 있고, 버전 관리 시스템에 친화적입니다.
#: includes/checkout.php:42
msgid "Add to Cart"
msgstr "In den Warenkorb"
#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr "Ihre Bestellung wurde an %s versandt"
msgid는 원문 영어 소스 문자열이며 절대 변경해서는 안 됩니다. msgstr은 번역입니다. %s는 번역본에 손상되지 않고 유지되어야 하는 자리 표시자(placeholder)입니다. 이를 누락하거나 순서를 바꾸는 것이 레이아웃 손상의 가장 흔한 원인이며, 이 내용은 코드 변수를 손상시키지 않고 PO 파일을 번역하는 방법에서 자세히 다룹니다.
.mo 파일: 컴파일된 바이너리
.mo 파일(Machine Object)은 .po 파일의 컴파일된 바이너리 버전입니다. WordPress는 런타임 시 .po 파일을 효율적으로 읽을 수 없으므로, 대신 미리 컴파일된 .mo 파일을 로드합니다. .mo 파일을 텍스트 편집기에서 열면 읽을 수 없는 바이트가 표시됩니다. 이 파일은 사람이 아닌 기계를 위한 것입니다.
WordPress가 load_textdomain() 또는 load_theme_textdomain()을 호출하면, .mo 파일을 찾고, 바이너리 해시 테이블을 구문 분석하고, 모든 msgid를 일치하는 msgstr로 즉시 교체합니다. 이 바이너리 형식은 수천 개의 문자열을 가진 사이트에서도 조회를 빠르게 만듭니다.
Gettext 워크플로우에서 세 파일은 어떻게 관련되나요?
이들은 단방향 파이프라인을 형성합니다: 소스 코드는 .pot이 되고, .pot은 언어별 .po가 되며, 각 .po는 .mo로 컴파일됩니다. 번역은 항상 하향식으로 흐릅니다.
다음은 전체 수명 주기 순서입니다:
- 개발자는 PHP 소스 코드 내에서
__()및_e()와 같은 Gettext 함수로 사용자에게 표시되는 문자열을 감쌉니다. - 스캔 도구가 소스를 읽고 감싸진 모든 문자열을 포함하는
.pot템플릿을 생성합니다. - 번역가는
.pot을 언어별.po(예:de_DE.po)로 복사하고 각msgstr을 채웁니다. - 완성된
.po파일은 바이너리.mo파일로 컴파일됩니다. - WordPress는 런타임에
.mo파일을 로드하여 번역된 사이트를 표시합니다.
개발자가 나중에 새로운 문자열을 추가하면 .pot 파일이 재생성되고, 새로운 항목이 각 기존 .po 파일에 병합되며 (이전 번역은 유지), 번역가가 빈칸을 채우고, .po 파일은 .mo 파일로 재컴파일됩니다. 이 주기는 프로젝트 수명 주기 동안 반복됩니다.
핵심 요점: 당신은 .po 파일을 편집한 다음 .mo 파일로 컴파일합니다. .mo 파일을 직접 편집하거나 .pot 파일 내에서 번역하지 마세요. 더 심층적인 전체 과정을 알고 싶다면, WordPress 지역화에 대한 궁극적인 가이드에서 예시와 함께 전체 파이프라인을 설명합니다.
명명 규칙 및 파일 저장 위치
WordPress는 파일 이름에 대해 엄격합니다. 이름을 잘못 지정하면 완벽하게 번역된 .mo 파일은 단순히 무시됩니다. WordPress는 텍스트 도메인과 로케일을 기반으로 정확히 일치하는 것을 찾기 때문입니다.
테마 및 플러그인 번역의 명명 패턴은 다음과 같습니다:
# Pattern: textdomain-locale.po / .mo
twentytwentyfour-de_DE.po # German (Germany) translation
twentytwentyfour-de_DE.mo # compiled binary WordPress loads
twentytwentyfour-fr_FR.po # French (France)
twentytwentyfour.pot # template, no locale suffix
textdomain은 __( 'Add to Cart', 'twentytwentyfour' )와 같은 Gettext 함수의 두 번째 인수로 전달된 문자열과 일치합니다. locale은 de_DE, fr_FR, pt_BR와 같은 WordPress 로케일 코드입니다. .pot 템플릿은 언어 중립적이므로 로케일 접미사가 없습니다.
위치도 이름만큼 중요합니다. WordPress는 몇 가지 예측 가능한 경로를 검색합니다:
- 테마 번역은 테마 자체의
wp-content/themes/your-theme/languages/폴더 내에 포함됩니다. - 플러그인 번역은
wp-content/plugins/your-plugin/languages/내에 포함됩니다. - translate.wordpress.org의 번역 및 사용자 재정의는 전역
wp-content/languages/themes/및wp-content/languages/plugins/디렉터리에 저장됩니다. 이는 우선순위를 가지며 업데이트 후에도 유지됩니다.
정확하게 이름이 지정된 de_DE.mo 파일을 올바른 폴더에 넣으면 독일 방문자는 독일어를 보게 됩니다. 파일을 한 폴더 더 깊숙이 넣거나 텍스트 도메인 이름을 잘못 입력하면, WordPress는 오류 메시지 없이 조용히 영어로 돌아갑니다. 번역이 표시되지 않는다면, 이름 지정 또는 경로 불일치가 일반적인 원인이며, 누락된 번역 문제 해결 가이드에서 모든 일반적인 원인을 다룹니다.
.mo 파일을 직접 편집해서는 안 되는 이유
.mo 파일은 컴파일된 바이너리이기 때문에 수동으로 안전하게 편집할 방법이 없으며, 강제로 적용한 변경 사항은 .po 파일이 다음에 재컴파일될 때 덮어쓰여집니다. .po는 진실의 원천(원본)이며, .mo는 일회성 빌드 아티팩트입니다.
이 단 하나의 규칙이 "내 번역이 변경되었지만 사이트가 업데이트되지 않았어요"와 같은 지원 티켓의 상당 부분을 설명합니다. 누군가 문자열을 약간 수정하고, .po를 저장하고, .mo를 재컴파일하는 것을 잊어버립니다. WordPress는 이전 바이너리를 계속 로드하므로 새로운 문구가 나타나지 않습니다. 해결책은 항상: .po를 편집하고, .mo로 재컴파일하고, 새로고침하는 것입니다.
이 규칙이 중요한 두 번째 이유가 있습니다: .mo 파일은 버전 관리에서 diff-친화적이지 않습니다. 이들은 바이너리이기 때문에, 작은 문구 변경이 Git 기록에 어떤 검토자도 읽을 수 없는 불투명한 덩어리(blob)를 생성합니다. .po를 추적되는 진실의 원천(원본)으로 유지하고 .mo를 생성된 아티팩트로 취급하면 리포지토리를 검토 가능하게 하고 번역을 감사 가능하게 유지합니다.
수십 가지 언어에 걸쳐 이 작업을 수동으로 수행하는 것은 지루하고 오류가 발생하기 쉽습니다. 이때 클라우드 워크플로우가 실제 시간을 절약해 줍니다. SimplePoTranslate와 같은 도구는 .po 문자열을 번역하고, 일치하는 .po 및 .mo 파일이 함께 포함된 단일 ZIP 파일을 돌려줍니다. 이미 컴파일되고, 올바르게 이름이 지정되었으며, wp-content/languages/에 바로 넣을 수 있습니다. 수동으로 컴파일할 필요가 없으며 오래된 .mo 파일이 발생할 가능성이 없습니다.
또한 번역 전에 %s, %1$s, {name}과 같은 모든 자리 표시자(placeholder)와 HTML 태그를 고정하는 **구문 잠금(Syntax Locking)**을 적용합니다. 변수가 손상되지 않고 유지되므로, 레이아웃을 손상시키는 .mo 파일을 배포할 일이 없습니다. 그리고 전적으로 클라우드에서 실행되므로, 사이트에 부담을 주는 추가 플러그인이 없습니다. 파일을 업로드하고 완성된, 컴파일된 번역을 다운로드합니다.
총정리
po vs mo 파일 구분이 명확해지면, 전체 WordPress 번역 시스템이 더 이상 신비롭게 느껴지지 않습니다. .pot은 개발자의 템플릿이고, .po는 번역가의 편집 가능한 작업 사본이며, .mo는 WordPress가 방문자에게 실제로 제공하는 컴파일된 바이너리입니다. 번역은 한 방향으로 흐릅니다 – 템플릿에서 .po로, 그리고 .po에서 .mo로 – 그리고 항상 중간 파일만 수동으로 편집합니다.
번역 관련 문제의 90%를 예방하는 세 가지 규칙을 기억하세요: .pot 파일 내에서 번역하지 마십시오. .po 파일을 편집한 후에는 항상 .mo 파일을 재컴파일하십시오. 그리고 textdomain-locale 명명 규칙을 정확히 일치시키십시오. 이 규칙들을 따르면 번역된 문자열이 항상 표시될 것입니다.
번역 파일을 수동으로 컴파일하고 이름 지정하는 어려움에서 벗어날 준비가 되셨습니까? SimplePoTranslate를 무료로 사용해보세요 — 신용카드 필요 없음. .po 또는 .pot 파일을 업로드하고 몇 분 안에 무료 티어에서 즉시 사용할 수 있는 .po + .mo 번들을 받으십시오.