WordPress 플러그인 번역하는 방법 (단계별 가이드)

프로젝트에 딱 맞는 WordPress 플러그인을 찾았습니다. 필요한 기능을 정확히 수행하고, 평점도 훌륭합니다. 그런데 플러그인을 활성화하고 나니 모든 버튼, 레이블, 오류 메시지가 영어로 되어 있는 것을 깨닫습니다. 독일어, 프랑스어, 일본어 사용자가 읽을 수 없는 텍스트의 벽에 부딪힐 순간입니다.

다행히 잘 만들어진 대부분의 플러그인은 번역 준비가 되어 있습니다(translation-ready). 이는 개발자가 여러분과 같은 사람들이 번역할 수 있도록 문자열을 Gettext 함수로 감쌌다는 의미입니다. 문제는 파일이 어디에 있는지, 번역 파일 이름을 어떻게 지정해야 하는지, 그리고 다음 플러그인 업데이트 시 작업 내용이 지워지지 않도록 파일을 어디에 두어야 하는지 아는 것입니다.

이 가이드는 WordPress 플러그인을 번역하는 방법을 처음부터 끝까지 보여줍니다. 텍스트 도메인과 언어 폴더를 찾고, .pot 템플릿을 얻거나 생성하고, 올바른 이름의 .po 및 .mo 파일을 만들고, WordPress가 안정적으로 로드할 수 있는 곳에 배치하는 방법을 다룹니다. 또한 이 방법으로는 완전히 번역할 수 없는 한 가지 유형의 플러그인에 대해서도 다룰 것이므로 불가능한 경우에 시간을 낭비하지 않도록 도와드립니다.

플러그인의 번역 파일은 어떻게 찾나요?

무엇이든 번역하기 전에 플러그인에서 두 가지 정보가 필요합니다. 바로 텍스트 도메인과 언어 폴더입니다. 텍스트 도메인은 플러그인이 자체 번역을 식별하는 데 사용하는 고유한 문자열이며, 언어 폴더는 원본 템플릿이 있는 곳입니다.

언어 폴더와 텍스트 도메인 찾기

wp-content/plugins/your-plugin/ 경로의 플러그인 디렉터리를 열고 /languages 하위 폴더를 찾으세요. 그 안에는 일반적으로 모든 번역 가능한 문자열을 포함하는 비어 있는 템플릿인 .pot 파일을 찾을 수 있습니다.

텍스트 도메인을 확인하려면 플러그인의 주요 PHP 파일을 열고 헤더 블록을 살펴보세요.

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

여기서 텍스트 도메인은 awesome-plugin입니다. 이 값은 매우 중요합니다. 번역 파일 이름에 이 값이 포함되어야만 WordPress가 해당 파일을 플러그인과 일치시킬 수 있기 때문입니다. 또한 코드 전체의 모든 문자열 호출에서도 이를 볼 수 있습니다.

echo __( 'Settings saved successfully.', 'awesome-plugin' );

두 번째 인수 awesome-plugin은 다시 텍스트 도메인입니다. 이 텍스트 도메인을 사용하는 모든 문자열은 번역 카탈로그로 번역될 수 있습니다. 만약 플러그인 인터페이스의 어떤 문자열이 이 래퍼 없이, 예를 들어 개발자가 __() 없이 echo 'Save'를 하드코딩했다면, 해당 문자열은 전혀 번역할 수 없으며 어떤 .po 파일도 도달할 수 없습니다. 대부분의 신뢰할 수 있는 플러그인은 모든 것을 올바르게 감싸지만, 번역되지 않는 고집스러운 문자열이 한두 개 있다면, 소스 코드에 Gettext 래퍼가 누락된 것이 원인일 가능성이 높습니다.

플러그인이 진정으로 번역 준비가 되어 있는지 빠르게 판단하는 방법은 WordPress.org 디렉터리에서 해당 플러그인의 목록을 확인하는 것입니다. 여기에는 번역 진행률이 표시되고 /languages 템플릿으로 연결되는 링크가 있습니다. 활성 번역 프로젝트가 있는 플러그인은 버려진 플러그인보다 깔끔하고 완전히 감싸진 문자열을 가질 가능성이 훨씬 높습니다.

플러그인에 POT 파일이 없다면?

일부 플러그인은 .pot 템플릿 없이 배포됩니다. /languages 폴더가 비어 있거나 없는 경우, 번역 가능한 문자열에 대한 소스 코드를 스캔하여 템플릿을 직접 생성해야 합니다.

이를 위한 표준 도구는 WP-CLI이며, 모든 Gettext 호출을 새 .pot 파일로 추출합니다.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

이 명령어는 플러그인의 PHP 및 JavaScript 파일을 탐색하여 모든 __(), _e(), _n() 및 관련 호출을 찾아 완전한 템플릿을 작성합니다. 그래픽 방식을 선호한다면 Poedit Pro도 같은 방식으로 소스 코드를 스캔할 수 있습니다. 어느 쪽이든 결과는 비어 있는 번역과 함께 모든 원본 문자열을 포함하는 .pot 파일이며, 실제 언어 파일로 전환할 준비가 된 것입니다.

자신만의 템플릿을 생성하는 것은 숨겨진 이점이 있습니다. 원본 개발자가 배포된 .pot 파일에 포함하는 것을 잊었을 수도 있는 문자열을 캡처합니다. 플러그인은 빠르게 진화하며, 2.1 버전과 함께 제공된 템플릿에는 2.4에서 추가된 문자열이 누락될 수 있습니다. 현재 소스에서 다시 생성하면 카탈로그가 두 릴리스 전에 표시된 내용이 아닌, 플러그인이 오늘날 실제로 표시하는 내용을 반영함을 보장합니다. 시간이 지남에 따라 플러그인 번역을 유지 관리하는 경우, 각 주요 업데이트 후에 make-pot를 다시 실행하는 것은 신뢰할 수 있는 습관입니다.

올바른 이름으로 PO 및 MO 파일 생성하기

플러그인을 번역할 때 가장 흔한 실수는 파일 이름입니다. WordPress는 매우 특정한 패턴과 일치시켜 플러그인 번역을 찾으며, 한 글자라도 틀리면 번역이 완전히 무시됩니다.

파일 이름 공식

플러그인 번역의 경우 패턴은 text-domain-locale입니다. 따라서 awesome-plugin 텍스트 도메인을 독일어로 번역하는 경우 파일 이름은 다음과 같아야 합니다.

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

로케일 코드는 WordPress 사이트 언어 코드입니다. 독일어는 de_DE, 프랑스어는 fr_FR, 스페인어는 es_ES, 브라질 포르투갈어는 pt_BR입니다. 로케일이 틀리면 WordPress는 파일을 자동으로 건너뜁니다. Poedit와 같은 편집기에서 .pot 템플릿을 사용하여 이 파일을 생성할 수 있으며, 저장 시 바이너리 .mo 파일을 자동으로 컴파일합니다. 이 편집기가 처음이라면, 완벽한 Poedit 가이드에서 템플릿에서 번역을 단계별로 생성하는 방법을 안내합니다.

업데이트 시 파일이 지워지지 않도록 파일을 배치하는 방법

두 가지 가능한 위치가 있으며, 올바른 위치를 선택하는 것이 중요합니다.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

항상 wp-content/languages/plugins/를 사용하세요. WordPress는 이 오버라이드 디렉터리를 먼저 확인하며, 플러그인 폴더 외부에 있기 때문에 플러그인 업데이트 시 번역 파일은 절대 건드려지지 않습니다. 플러그인 자체 폴더 내에 배치된 파일은 새 버전이 설치되는 순간 덮어쓰여집니다.

이 오버라이드 동작은 WordPress 현지화의 가장 유용하면서도 잘 알려지지 않은 기능 중 하나입니다. 이는 어떤 타사 플러그인이든 포크(fork)하지 않고도 사용자 정의 또는 수정된 번역을 배포할 수 있으며, 변경 사항은 업데이트에도 안전하다는 것을 의미합니다. 동일한 플러그인을 사용하는 여러 클라이언트 사이트를 관리하는 경우, 단일 오버라이드 .mo 파일 세트를 유지하고 모든 사이트에 배포할 수 있으며, 로케일이 일치하는 한 각 사이트에서 자동으로 이 파일을 가져올 것을 알 수 있습니다.

WordPress가 번역을 로드하는 방법

번역 준비가 된 플러그인은 초기화 중에 load_plugin_textdomain()을 호출하여 WordPress에 카탈로그를 로드하도록 지시합니다.

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

WordPress 4.6 이상 버전의 대부분의 최신 플러그인의 경우, 이 부분을 건드릴 필요가 없습니다. 파일 이름과 사이트 로케일이 일치하는 한, WordPress는 wp-content/languages/plugins/에서 번역을 자동으로 로드합니다. 완성된 번역이 여전히 나타나지 않는다면, 그 원인은 거의 항상 파일 이름 불일치, 오래된 .mo 파일 또는 잘못된 로케일로 설정된 사이트 언어입니다. 번역이 WordPress에 표시되지 않는 문제 해결 가이드에서 이러한 모든 실패 지점을 자세히 안내합니다.

문자열을 데이터베이스에 저장하는 플러그인

여기에 중요한 제한 사항이 있습니다. Gettext 방식은 플러그인 코드에 존재하는 문자열만 번역합니다. 일부 플러그인, 특히 폼 빌더, 페이지 빌더 및 전자상거래 확장 기능은 WordPress 데이터베이스에 저장되는 콘텐츠(폼 레이블, 제품 속성, 사용자 정의 메시지)를 생성할 수 있도록 합니다. 이러한 문자열은 .pot의 일부가 아닌 사용자 생성 데이터이므로 .po 파일로는 번역할 수 없습니다. 데이터베이스 콘텐츠의 경우 WPML 또는 Polylang과 같은 다국어 플러그인 또는 플러그인 자체의 문자열 번역 기능이 필요합니다. .po 파일이 문제를 해결할 수 있다고 가정하기 전에, 특정 문자열이 코드에 있는지 데이터베이스에 있는지 항상 테스트하세요.

간단한 테스트를 통해 어떤 종류의 문자열을 다루고 있는지 알 수 있습니다. 설정 필드에 입력한 텍스트, 생성한 폼 레이블, 사용자 지정 감사 메시지, 제품 이름이라면 데이터베이스 콘텐츠이므로 .po 파일로는 번역할 수 없습니다. 텍스트가 플러그인의 내장 인터페이스(버튼 레이블, 유효성 검사 오류, 플러그인 자체와 함께 제공되는 관리자 알림)의 일부라면 코드에 존재하며 .po 파일이 정확히 올바른 도구입니다. 이 경계를 일찍 파악하면 몇 시간의 좌절을 덜 수 있습니다. 플러그인이 런타임에 데이터베이스에서 가져오는 문자열은 아무리 완벽한 .po 파일 편집으로도 번역할 수 없기 때문입니다.

수동 작업 없이 대규모로 번역하기

플러그인 하나를 한 가지 언어로 수동 번역하는 것은 관리할 수 있습니다. 하지만 이를 열 가지 언어로 번역하거나 클라이언트 사이트용으로 전체 플러그인 스택을 번역하는 것은 며칠간의 반복적인 작업이 되며, 모든 수동 편집은 %s 또는 %1$s와 같은 플레이스홀더를 잘못 다루어 출력을 손상시킬 위험이 있습니다.

바로 여기서 클라우드 워크플로우가 계산을 바꿉니다. 플러그인의 .po 또는 .pot 파일을 SimplePoTranslate에 업로드하고, 번역할 언어를 선택하면 상황 인식 AI가 전체 카탈로그를 번역하는 동안 Syntax Locking이 모든 플레이스홀더, HTML 태그 및 코드 토큰을 고정하여 아무것도 손상되지 않도록 합니다. Smart Batching은 대규모 카탈로그를 한 번에 처리하며, .po, .mo, .json, .php, .xliff 파일을 함께 포함하는 ZIP 파일을 다운로드할 수 있습니다. 이 파일들은 wp-content/languages/plugins/에 바로 넣을 수 있도록 올바르게 포맷되어 있습니다. 모든 작업은 클라우드에서 실행되므로 데스크톱 설치나 사이트에 불필요한 부하가 없습니다.

플러그인 번역은 폴더 규칙과 로딩 함수가 약간 다른 테마 번역과 다르다는 점에 유의하세요. 테마가 대상이라면, 개발자가 아니더라도 모든 WordPress 테마를 현지화하는 방법에 대한 전용 가이드를 따르세요.

플러그인 하나와 언어 하나만 필요할 때는 수동 방식을 사용하세요. 여러 언어가 빠르게 필요하고 플레이스홀더 안전성을 놓치지 않으려면 클라우드를 사용하세요.

변수를 하나도 손상시키지 않고 대상 독자가 사용하는 모든 언어로 WordPress 플러그인을 번역할 준비가 되셨나요? SimplePoTranslate를 무료로 사용해보세요 — 신용 카드 정보는 필요 없습니다. 무료 티어에서는 몇 분 만에 첫 플러그인 .po 파일을 번역할 수 있으며, 모든 문자열에 Syntax Locking 기능이 적용됩니다.