테마 또는 플러그인을 위한 .pot 파일 생성 방법

방금 전 세계와 공유하고 싶은 WordPress 플러그인을 완성했습니다. 코드는 작동하고, 기능은 탄탄하며, 독일에 사는 누군가가 독일어로 번역하는 방법을 묻는 이메일을 보냅니다. 당신은 그들에게 languages 폴더를 가리키지만, 그곳에 아무것도 없다는 것을 깨닫습니다. 템플릿도, 문자열도 없어서 번역가는 무엇을 번역해야 하는지조차 알 수 없습니다. 당신의 플러그인은 기술적으로 이름만 "번역 준비 완료" 상태인 것입니다.

번역 가능한 모든 WordPress 프로젝트는 하나의 파일, 즉 .pot 템플릿으로 시작합니다. 누군가 독일어, 프랑스어 또는 일본어 버전을 만들기 전에, 코드에 있는 모든 사용자 대상 문자열을 나열하는 POT 파일을 생성해야 합니다. 이 단계를 건너뛰면 번역가들은 소스 코드를 줄별로 읽어가며 어떤 문자열이 사용자에게 표시되어야 하는지 추측해야 합니다.

이 가이드는 작업의 두 가지 절반을 다룹니다: 문자열을 검색 가능하도록 소스 코드를 준비하는 것, 그리고 세 가지 다른 도구를 사용하여 .pot 자체를 생성하는 것입니다. 우리는 WP-CLI, Poedit, 그리고 레거시 makepot/grunt 접근 방식을 실제 복사할 수 있는 명령과 함께 사용할 것입니다. 이 가이드를 마치면 어떤 번역가에게도 넘겨줄 수 있는 깨끗한 템플릿을 갖게 될 것입니다.

1단계: 문자열을 번역 가능으로 표시하기

POT 파일을 생성하기 전에 사용자가 볼 수 있는 모든 문자열은 Gettext 함수로 래핑되어야 합니다. 스캐너는 자신이 인식하는 문자열만 추출할 수 있으며, 이러한 함수 호출을 통해 문자열을 인식합니다. 일반 문자열 리터럴은 스캐너에게 보이지 않습니다.

WordPress는 각각 약간 다른 컨텍스트를 위한 여러 현지화 함수를 제공합니다:

// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );

// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );

// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );

// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );

모든 호출의 두 번째 인수 — 'my-plugin' —는 텍스트 도메인입니다. 이것은 플러그인 또는 테마의 모든 문자열을 하나의 네임스페이스 아래에 그룹화하여 WordPress가 어떤 .mo 파일을 로드해야 하는지 알 수 있도록 합니다. 프로젝트의 모든 번역 가능한 문자열은 정확히 동일한 텍스트 도메인을 공유해야 하며, 그렇지 않으면 일부 문자열은 번역되지 않을 것입니다.

단어가 모호할 때는 언제든지 _x()를 사용하세요. 영어 "Post"는 명사 또는 동사가 될 수 있으며, 많은 언어에서 다르게 번역됩니다. 컨텍스트 문자열을 통해 번역가들은 이들을 구별할 수 있습니다. 그리고 번역된 문자열이 HTML로 출력될 때는 esc_html__() 및 esc_attr__() 변형을 사용하여 안전하고 동시에 현지화되도록 하세요.

문자열을 추출 가능하게 유지하는 몇 가지 습관이 있습니다. 항상 일반 문자열 리터럴을 첫 번째 인수로 전달하세요. 변수나 __( 'Hello ' . $name, 'my-plugin' )과 같은 연결은 절대로 안 됩니다. 스캐너는 소스 텍스트를 정적으로 읽고 런타임 값을 확인할 수 없기 때문입니다. 숫자가 포함된 문장에는 _n()을 사용하여 복수형이 올바르게 캡처되도록 하고, 동적 값이 포함된 문장에는 문자열을 연결하는 대신 %s와 같은 자리 표시자 주위에 sprintf()를 사용하세요. 이러한 일관성이 다음 단계, 즉 템플릿 생성이 완전하고 사용 가능한 결과를 만드는 이유입니다.

2단계: 헤더에 텍스트 도메인 선언하기

WordPress는 번역이 어디에 있는지 알기 위해 두 가지 헤더 필드가 필요합니다: 텍스트 도메인과 도메인 경로. 플러그인의 메인 파일 또는 테마의 style.css에 이를 설정하면 WordPress는 런타임에 올바른 .mo를 자동으로 로드합니다.

<?php
/**
 * Plugin Name:       My Plugin
 * Description:        A perfectly localized WordPress plugin.
 * Version:            1.0.0
 * Requires at least: 6.4
 * Text Domain:       my-plugin
 * Domain Path:       /languages
 */

텍스트 도메인은 모든 __() 및 _e() 호출에 전달한 문자열, 여기서는 my-plugin과 일치해야 합니다. 도메인 경로는 WordPress에게 플러그인 또는 테마 루트를 기준으로 번역 파일이 있는 하위 폴더를 알려줍니다. 관례는 /languages이며, 생성된 .pot 파일이 정확히 그곳에 있어야 합니다.

문자열을 래핑하고 헤더를 선언하면 코드를 스캔할 준비가 된 것입니다. 자신의 테마가 아닌 경우를 포함하여 프로젝트를 번역할 준비를 하는 더 넓은 그림은 개발자가 아니더라도 모든 WordPress 테마를 현지화하는 방법에서 다룹니다.

.pot 파일을 생성하는 방법: 세 가지 방법

소스 코드를 스캐너로 실행하여 모든 Gettext 호출을 찾아 문자열을 템플릿에 작성함으로써 .pot 파일을 생성합니다. 다음은 최신 기본 방식부터 레거시 접근 방식까지 세 가지 신뢰할 수 있는 방법입니다.

방법 1: WP-CLI (권장)

POT 파일을 생성하는 공식적이고 현대적인 방법은 i18n 명령을 사용하는 WP-CLI입니다. 이것은 WordPress 코어 툴링의 일부로 제공되며, PHP 및 JavaScript 문자열을 이해하고 한 줄로 표준을 준수하는 템플릿을 생성합니다.

# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot

# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin

# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules

첫 번째 인수는 소스 디렉터리(현재 폴더의 경우 .), 두 번째 인수는 출력 경로입니다. WP-CLI는 파일을 탐색하고, 래핑된 모든 문자열을 추출하며, 소스 파일과 줄 번호를 주석으로 기록하고, .pot 파일을 작성합니다. 이것은 빠르고, 스크립트 가능하며, 모든 진지한 프로젝트에 적합한 선택입니다.

생성된 템플릿에는 추가 플래그로 조정할 수 있는 유용한 메타데이터가 포함됩니다. --headers를 전달하여 프로젝트 이름, 버전 및 번역가의 연락처 주소를 설정하면 .pot 헤더 블록이 자리 표시자로 남지 않고 올바르게 채워집니다. WP-CLI는 또한 wp_set_script_translations() 호출에서 JavaScript 문자열을 자동으로 추출하는데, 이는 사용자 대상 텍스트의 절반이 PHP가 아닌 JavaScript에 존재하는 현대적인 블록 테마 및 Gutenberg 플러그인에 중요합니다. 하나의 명령으로 두 가지 모두를 처리합니다.

방법 2: Poedit (그래픽)

데스크톱 앱을 선호한다면, Poedit는 인터페이스를 통해 소스를 스캔하고 템플릿을 생성할 수 있습니다. Poedit을 열고, POT에서 새 번역을 생성하거나 소스를 직접 스캔하도록 선택한 다음, 프로젝트 폴더를 지정하고 카탈로그 속성에서 소스 키워드(__, _e, _x, esc_html__)를 구성하세요.

Poedit의 소스 스캔 및 .pot 생성 기능은 Pro 에디션에 있지만, 명령을 입력하는 것보다 클릭하는 것을 선호하는 개발자에게는 친숙한 워크플로를 제공합니다. 또한 이어지는 번역 단계에 훌륭한 편집기이기도 합니다. Poedit과 다른 몇 가지 데스크톱 옵션은 Mac 및 Windows에서 PO 파일을 편집하고 번역하는 데 사용할 수 있는 상위 5가지 무료 도구에서 비교됩니다.

방법 3: makepot / grunt (레거시)

WP-CLI 이전에 표준 도구는 WordPress i18n-tools 저장소의 makepot.php 스크립트였으며, 종종 grunt-wp-i18n을 사용하여 Grunt 빌드 작업에 연결되었습니다. 구형 플러그인 및 테마에서 여전히 이를 접할 수 있습니다.

# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot

이것은 작동하지만, WP-CLI에 비해 유지보수되지 않으며 설정하는 데 더 많은 시간이 걸립니다. 이미 의존하고 있는 레거시 프로젝트를 유지보수할 때만 사용하세요. 새로운 프로젝트의 경우 wp i18n make-pot를 선호하세요.

코드 변경 시 템플릿을 최신 상태로 유지하기

.pot 파일은 특정 시점의 문자열 스냅샷입니다. 기능을 추가하거나, 레이블을 변경하거나, 표시되는 문자열의 오타를 수정할 때마다 템플릿은 오래되어 번역가들이 새로운 문구를 놓치게 됩니다.

재생성을 릴리스 루틴의 일부로 만드세요. 버전이 올라갈 때마다 wp i18n make-pot를 다시 실행한 다음, 새로 고쳐진 템플릿을 wp i18n update-po 또는 msgmerge를 사용하여 기존 번역에 병합하여 번역가들이 완성된 작업을 유지하고 새로운 누락 부분만 확인하도록 하세요. .pot 파일을 수동으로 편집하는 파일이 아니라 재생성하는 빌드 아티팩트로 취급하세요.

오래된 템플릿은 미묘하고 좌절스러운 실패를 초래합니다: 번역가가 작업한 .pot 파일에 새로운 문자열이 포함되지 않았기 때문에 "완전히 번역된" 사이트에서도 새로운 문자열이 영어로 표시됩니다. 이를 방지하는 것은 빌드에 재생성을 스크립팅하는 것만큼 간단하며, 템플릿이 코드보다 뒤쳐지지 않도록 보장합니다. 일부 팀은 .pot 파일 재생성이 diff를 생성하면 빌드가 실패하도록 CI 검사를 추가하여, 커밋된 템플릿이 항상 현재 소스와 일치하도록 보장합니다.

번역가들이 완성된 .po 파일을 반환하면, 이 파일들은 WordPress가 실제로 로드하는 바이너리 .mo로 컴파일되어야 합니다. 만약 전체 다운로드-번역-재컴파일 루프를 건너뛰고 싶다면, 클라우드 도구가 처음부터 끝까지 처리할 수 있습니다. SimplePoTranslate는 .pot 파일을 직접 받아들여, 인터페이스에서 각 문자열이 무엇을 의미하는지 이해하는 Context-Aware AI로 번역한 다음, 이미 빌드되고 이름이 지정된 .po, .mo 등을 포함한 단일 ZIP 파일을 반환합니다. Syntax Locking 기능은 %s 및 %1$s와 같은 자리 표시자를 고정하여 번역 중에 변수가 손상되지 않도록 합니다.

마무리

POT 파일을 올바르게 생성하려면 먼저 코드를 검색 가능하게 만드세요. 즉, 모든 보이는 문자열을 __(), _e(), _x() 또는 이스케이프 변형으로 래핑하고, 모두 하나의 텍스트 도메인을 공유하며, 헤더에 해당 도메인과 Domain Path를 선언해야 합니다. 그런 다음, 새 프로젝트의 경우 WP-CLI로, GUI를 선호하는 경우 Poedit으로, 레거시 코드를 유지보수하는 경우에만 makepot으로 템플릿을 생성하세요.

일찍 생성하고, 자주 재생성하며, 템플릿이 코드보다 뒤쳐지지 않도록 하세요. 최신 .pot 파일은 플러그인이 진정으로 전 세계에 준비된 것과 단순히 그렇다고 주장하는 것의 차이입니다.

수동 컴파일 과정 없이 .pot 템플릿을 완성된 번역으로 바꾸고 싶으신가요? SimplePoTranslate를 무료로 사용해 보세요 — 신용카드 필요 없습니다. 무료 티어에서 템플릿을 업로드하고 몇 분 안에 배포 가능한 번역 파일을 다운로드하세요.