.po 파일을 .mo 파일로 컴파일하는 방법 (4가지 방법)

오후 내내 독일어 번역을 완벽하게 다듬었습니다. de_DE.po 파일의 모든 문자열은 아름답게 읽히고, 플레이스홀더는 손상되지 않았으며, 복수형도 정확합니다. 이를 사이트에 업로드하고 언어를 독일어로 전환했지만... 아무것도 바뀌지 않습니다. 페이지는 여전히 영어로 표시됩니다. 파일 이름, 폴더, 텍스트 도메인을 다시 확인합니다. 모든 것이 올바르게 보입니다. 그렇다면 왜 WordPress는 번역을 표시하지 않을까요?

열에 아홉은 답이 같습니다. 바로 .po 파일을 편집했지만 .mo 파일로 컴파일하지 않았기 때문입니다. WordPress는 런타임에 .po 파일을 읽지 않습니다. 컴파일된 바이너리 .mo 파일을 로드합니다. 번역이 실제로 표시되게 하려면 텍스트를 변경할 때마다 .po 파일을 .mo 파일로 컴파일해야 합니다. .po는 편집 가능한 원본이고, .mo는 사이트에서 제공하는 파일입니다.

이 가이드는 컴파일 단계가 왜 존재하는지 설명하고, 이를 수행하는 네 가지 신뢰할 수 있는 방법인 WP-CLI, 고전적인 msgfmt 명령어, Poedit, 그리고 .mo 파일을 자동으로 생성해주는 클라우드 도구를 안내합니다. 또한 가장 흔한 함정인 재컴파일을 잊는 경우와 WordPress가 현재 속도를 위해 선호하는 새로운 .l10n.php 형식에 대해서도 다룹니다.

WordPress는 왜 .po가 아닌 .mo를 로드할까요?

WordPress는 .mo 파일을 로드합니다. .mo 파일은 빠른 조회를 위해 최적화된 컴파일된 바이너리인 반면, .po 파일은 사람이 읽고 편집하기 위한 일반 텍스트이기 때문입니다. 페이지 로드마다 텍스트를 파싱하는 것은 느릴 수 있지만, 미리 구축된 바이너리 해시 테이블을 읽는 것은 거의 즉각적입니다.

.po 파일은 줄 기반이며 사람이 읽기 쉽습니다. 각 항목은 원본 msgid와 번역된 msgstr을 짝지으며, 문자열 출처를 나타내는 주석이 추가됩니다. 이는 편집에는 훌륭하지만 성능에는 치명적입니다. 서버는 각 요청마다 전체 텍스트 파일을 다시 파싱해야 하기 때문입니다.

#: includes/cart.php:88
msgid "Your cart is empty"
msgstr "Ihr Warenkorb ist leer"

.mo 파일은 동일한 문자열 쌍을 내부 조회 테이블이 있는 바이너리 형식으로 압축하여 WordPress가 텍스트를 스캔하지 않고도 번역으로 바로 이동할 수 있도록 합니다. 단점은 .mo는 사람이 읽을 수 없으며 .po가 변경될 때마다 다시 생성해야 한다는 것입니다. .po와 .mo의 구분이 여전히 모호하다면, .po, .mo, .pot 파일 설명서에서 각 형식과 그 관계를 자세히 설명합니다.

.po 파일을 .mo 파일로 컴파일하는 4가지 방법

단 하나의 "올바른" 도구는 없습니다. 최선의 선택은 현재 작업 방식에 따라 달라집니다. 아래에는 한 줄 명령어부터 완전 자동화된 클라우드 워크플로까지 네 가지 신뢰할 수 있는 방법이 있습니다. 이 네 가지 방법 모두 WordPress가 런타임에 로드하는 동일한 바이너리 .mo 파일을 생성합니다.

방법 1: WP-CLI

가장 깔끔한 최신 접근 방식은 WP-CLI입니다. WP-CLI는 하나의 명령으로 .po 파일 폴더 전체를 컴파일할 수 있습니다. 이미 명령줄에서 WordPress를 관리하고 있다면, 이는 워크플로에 자연스럽게 들어맞을 것입니다.

# Compile every .po file in the languages folder to .mo
wp i18n make-mo languages/

# Compile into a specific destination directory
wp i18n make-mo languages/ build/languages/

make-mo 명령어는 대상 디렉토리를 스캔하고, 발견한 각 .po 파일을 컴파일하며, 그 옆에 일치하는 .mo 파일을 작성합니다 (또는 지정한 대상에). 이는 일괄 처리를 원활하게 처리하여 여러 언어를 동시에 유지 관리할 때 이상적입니다. WP-CLI를 이미 사용하고 있는 모든 프로젝트에 권장되는 도구입니다.

방법 2: msgfmt

이 작업을 위한 원본 Gettext 유틸리티는 GNU gettext 패키지의 일부인 msgfmt입니다. 이는 단일 .po 파일을 단일 .mo 파일로 컴파일하며, 거의 모든 Linux 및 macOS 시스템에서 사용할 수 있습니다.

# Compile one file
msgfmt my-plugin-de_DE.po -o my-plugin-de_DE.mo

# Add statistics about translated, fuzzy, and untranslated strings
msgfmt --statistics my-plugin-de_DE.po -o my-plugin-de_DE.mo

# Install it first if missing
#   macOS:  brew install gettext
#   Debian: sudo apt-get install gettext

-o 플래그는 출력 파일의 이름을 지정합니다. --statistics 플래그는 정말 유용합니다. 얼마나 많은 문자열이 번역되었는지, 불확실한지, 또는 아직 비어 있는지 알려주어 불완전한 번역을 배포하기 전에 파악할 수 있도록 돕습니다. 한 번에 한 파일을 스크립팅하는 경우 msgfmt는 믿을 수 있고 간소한 선택입니다.

msgfmt는 일반적인 명령줄 도구이므로 자동화에 깔끔하게 통합됩니다. 셸 루프에 묶어 전체 폴더를 컴파일하거나, CI 파이프라인에 연결하여 .po 파일에 변경이 있는 모든 커밋이 새 .mo 파일을 자동으로 생성하도록 할 수 있습니다. 일반적인 패턴은 for f in languages/*.po; do msgfmt "$f" -o "${f%.po}.mo"; done이며, 이는 모든 언어를 한 번에 컴파일합니다. --check 플래그는 유효성 검사를 추가하여 msgid와 msgstr 간의 형식 문자열 불일치를 프로덕션에 도달하기 전에 표시해줍니다. 이는 번역된 레이아웃을 조용히 손상시키는 깨진 플레이스홀더 버그에 대한 저렴한 안전장치입니다.

방법 3: Poedit (저장 시 컴파일)

그래픽 편집기에서 번역을 편집하는 경우, Poedit이 자동으로 컴파일해줍니다. .po 파일을 저장할 때마다 Poedit은 일치하는 .mo 파일을 바로 옆에 작성합니다. 별도의 명령이나 추가 단계가 필요 없습니다.

이것이 Poedit이 명령줄에 익숙하지 않은 번역가들 사이에서 계속 인기를 끄는 이유 중 하나입니다. .po 파일을 열고 번역을 입력한 후 저장을 누르면 두 파일이 함께 업데이트됩니다. Poedit 환경설정에서 기본적으로 자동 .mo 컴파일이 활성화되어 있으므로 이 동작을 확인할 수 있습니다. Poedit 및 유사한 데스크톱 도구는 Mac 및 Windows에서 PO 파일을 편집하고 번역하는 데 사용할 수 있는 최고의 무료 도구 5가지에서 검토됩니다.

데스크톱 편집기의 단점은 컴파일이 사람이 파일을 열고 저장할 때만 발생한다는 것입니다. 이는 1인 프로젝트에는 괜찮지만, 수십 개의 언어나 파일을 주고받는 팀에는 확장성이 없습니다. 누군가 다른 도구에서 .po 파일을 편집하고 Poedit을 열지 않고 리포지토리에 복사하면, .mo 파일은 절대 업데이트되지 않습니다. 더 크거나 협업하는 프로젝트의 경우, 자동화된 방법(명령줄 또는 클라우드)은 저장 버튼을 누르는 것을 기억해야 하는 의존성을 제거합니다.

방법 4: .mo 파일을 자동으로 생성해주는 클라우드 도구

네 번째 옵션은 컴파일 단계를 완전히 제거합니다. 번역된 .po 파일과 함께 컴파일된 .mo 파일을 반환하는 클라우드 서비스를 사용하는 것입니다. 명령을 실행하거나 파일을 두 번 저장할 필요 없이, 업로드하면 올바르게 이름이 지정된 완성된 파일이 돌아옵니다.

SimplePoTranslate는 정확히 이런 방식으로 작동합니다. .po 또는 .pot 파일을 업로드하면, Context-Aware AI로 문자열을 번역하고, .po와 .mo가 함께 생성된 단일 ZIP 파일을 반환합니다. 이미 컴파일되어 있고, 텍스트 도메인 및 로케일에 맞게 이름이 지정되어 있습니다. 별도의 컴파일 과정이 없으며, 잊어버릴 염려도 없습니다.

또한 수동 워크플로를 방해하는 세부 사항도 처리합니다. **구문 잠금(Syntax Locking)**은 %s, %1$s, {name}과 같은 플레이스홀더 및 HTML 태그를 번역 전에 고정하여 변수가 .mo 파일에 손상되지 않고 유지되도록 합니다. 완전한 Gettext 복수형 지원은 복잡한 복수형 형식도 올바르게 컴파일됨을 의미합니다. 이는 깊이 이해할 가치가 있는 주제이며, Gettext 복수형 이해하기에서 다룹니다. 클라우드에서 실행되므로 설치할 플러그인이나 유지 관리할 빌드 도구가 없습니다.

가장 흔한 함정: 재컴파일을 잊었다는 것

번역이 나타나지 않는 가장 큰 이유는 .po 파일을 편집했지만 .mo 파일을 재컴파일하는 것을 잊었기 때문입니다. WordPress는 계속해서 이전 바이너리를 로드하므로, 새로 번역된 내용은 절대 표시되지 않으며, 그 이유를 알려주는 오류 메시지도 없습니다.

기억해야 할 핵심 개념: .po는 초안이고, .mo는 배포되는 파일입니다. .po 파일에 대한 모든 변경 사항은 .mo 파일을 다시 생성할 때까지 WordPress에 보이지 않습니다. 모든 편집 후 재컴파일을 반사적으로 수행하거나, 단계가 절대 건너뛰어지지 않도록 자동으로 컴파일하는 도구를 사용하십시오.

이 함정은 스테이징에서 프로덕션으로의 인계 과정에서 특히 교묘합니다. 개발자는 로컬에서 편집하고 재컴파일하여 번역이 작동하는 것을 확인한 다음, .po 파일만 배포하고 .mo 파일을 잊어버리는 경우가 있습니다. 그래서 프로덕션에서는 조용히 이전 텍스트를 유지합니다. 환경 간에 번역 파일을 이동할 때는 .po와 새로 컴파일된 .mo 파일을 함께 이동하거나, 배포 단계의 일부로 컴파일하여 바이너리가 항상 현재 소스에서 다시 빌드되도록 하십시오.

재컴파일 후에도 번역이 계속 나타나지 않는다면, 문제는 일반적으로 이름 불일치, 잘못된 폴더, 또는 오래된 파일을 보관하고 있는 캐싱 계층 때문입니다. 전체 체크리스트는 WordPress에서 번역이 표시되지 않는 이유에서 확인할 수 있습니다.

새로운 .l10n.php 형식에 대한 참고 사항

최신 WordPress 버전은 세 번째 런타임 형식을 도입했습니다: **.l10n.php**입니다. 바이너리 .mo 대신 번역은 PHP 옵코드 캐시가 메모리에 저장할 수 있는 일반 PHP 배열로 저장되어, 트래픽이 많은 사이트에서 .mo보다 훨씬 빠른 조회를 가능하게 합니다.

<?php
return [
	'domain'  => 'my-plugin',
	'messages' => [ 'Your cart is empty' => 'Ihr Warenkorb ist leer' ],
];

WordPress는 일치하는 .mo 파일을 사용할 수 있을 때 .l10n.php 파일을 자동으로 생성하므로, 수동으로 만들 필요가 없습니다. 현재로서는 올바른 .mo 파일을 컴파일하는 것이 여전히 기본이며, 성능 향상 형식은 여기에서 파생됩니다.

마무리

.po 파일을 .mo 파일로 안정적으로 컴파일하려면 작업 방식에 맞는 방법을 선택하십시오: 명령줄 일괄 처리를 위한 WP-CLI, 통계와 함께 단일 파일을 위한 msgfmt, 저장 시 자동 컴파일을 위한 Poedit, 또는 단계를 건너뛸 일이 없도록 .mo 파일을 자동으로 빌드해주는 클라우드 도구입니다. 이 네 가지 방법 모두 WordPress가 런타임에 필요로 하는 동일한 바이너리를 생성합니다.

어떤 방법을 선택하든 황금률을 기억하십시오: .po를 편집한 다음, .mo로 컴파일하십시오. 매번 말입니다. 이 한 가지 습관만으로 WordPress에서 가장 골치 아픈 번역 버그, 즉 모든 것이 올바르게 보이지만 사이트가 고집스럽게 영어로 남아있는 버그를 예방할 수 있습니다.

수동 컴파일 단계를 영원히 건너뛸 준비가 되셨나요? SimplePoTranslate를 무료로 사용해 보세요 — 신용 카드 정보가 필요 없습니다. .po를 업로드하고 무료 티어에서 몇 분 안에 바로 배포 가능한 .po + .mo 번들을 다운로드하십시오.