워드프레스 JSON 번역: 블록 편집기 자바스크립트 번역

플러그인을 번역했습니다. PHP 문자열은 관리자 설정, 프런트엔드 템플릿, 이메일 알림 등 모든 곳에서 완벽하게 현지화되어 나타납니다. 그런데 블록 편집기를 열면 사용자 정의 Gutenberg 블록의 모든 레이블이 완강하고 조롱하듯이 영어로 되어 있습니다. "항목 추가" 버튼, 검사기 패널 제목, 자리표시자 텍스트까지요. .mo 파일은 로드되어 있는데, 왜 이 문자열들은 번역되지 않을까요?

WordPress 5.0과 Gutenberg의 등장 이후로, 자바스크립트 문자열은 .mo 파일에서 전혀 오지 않기 때문입니다. 자바스크립트 문자열은 완전히 별개의 스크립트별 워드프레스 JSON 번역 파일을 필요로 하며, 이 파일을 생성하지 않으면 .po 파일이 아무리 완벽하게 번역되어 있더라도 블록 편집기는 영어로 남아 있습니다. 이는 최신 WordPress 개발에서 가장 흔하고 혼란스러운 현지화 문제 중 하나입니다. 이 가이드는 왜 이런 현상이 발생하는지, JSON 번역 시스템이 어떻게 작동하는지, 모두를 헷갈리게 하는 MD5 해시 파일명에 대해, 그리고 이 문제를 해결하기 위한 전체 도구 체인을 정확하게 설명합니다.

블록 편집기 문자열이 영어로 남아있는 이유

간단히 말해서: PHP와 자바스크립트는 WordPress에서 완전히 다른 두 가지 번역 제공 시스템을 사용하며, .mo 파일은 PHP 시스템에만 데이터를 제공합니다.

두 개의 번역 시스템, 하나의 플러그인

WordPress가 load_plugin_textdomain()을 실행할 때, 컴파일된 .mo 파일을 PHP 메모리로 읽어들입니다. PHP 코드의 모든 __(), _e(), _x() 호출은 거기에서 해당 번역을 찾습니다. PHP는 서버 측에서 렌더링되므로 .mo 데이터가 동일한 프로세스에 있기 때문에 이것이 작동합니다.

자바스크립트는 다릅니다. 블록 코드는 PHP가 실행을 마친 훨씬 후에 브라우저에서 실행됩니다. 서버 측 .mo 파일에 접근할 수 없습니다. 대신, @wordpress/i18n 패키지(Gettext의 JS 버전으로, 스크립트에 __(), _x(), sprintf()를 노출함)는 번역이 해당 스크립트에 첨부된 JSON 페이로드 형태로 전달되기를 기대합니다.

번역되지 않은 JS 문자열은 어떻게 되는가

따라서 다음과 같은 문자열을 포함하는 블록은:

import { __ } from '@wordpress/i18n';

registerBlockType( 'myplugin/feature-box', {
    title: __( 'Feature Box', 'myplugin' ),
    edit: () => {
        return <Button>{ __( 'Add Item', 'myplugin' ) }</Button>;
    },
} );

브라우저가 .mo 파일을 읽지 않으므로 .mo 파일에서 "Feature Box"나 "Add Item"을 찾을 수 없습니다. 이 문자열들은 이 정확한 스크립트 핸들에 연결된 JSON으로 전달되어야 합니다. 이를 설정하지 않았다면, JS __() 호출은 콘솔에 아무런 오류 없이 원래 영어를 반환할 뿐입니다.

wp_set_script_translations()로 JSON 번역 연결하기

스크립트와 JSON 번역을 연결하는 다리는 단 하나의 PHP 함수, wp_set_script_translations()입니다. 'WordPress는 어떤 JSON 파일이 어떤 스크립트에 속하는지 어떻게 아는가'에 대한 답은 다음과 같습니다: 스크립트를 등록하고 해당 텍스트 도메인과 JSON 파일이 있는 폴더를 선언하여 WordPress에 알려주는 것입니다.

스크립트 및 번역 폴더 등록하기

add_action( 'init', function () {
    wp_register_script(
        'myplugin-editor',
        plugins_url( 'build/index.js', __FILE__ ),
        array( 'wp-blocks', 'wp-i18n', 'wp-element' ),
        '1.0.0'
    );

    // Tell WordPress where this script's JSON translations live
    wp_set_script_translations(
        'myplugin-editor',        // the registered script handle
        'myplugin',               // text domain
        plugin_dir_path( __FILE__ ) . 'languages'
    );
} );

편집기가 myplugin-editor를 로드할 때, WordPress는 이제 languages/ 폴더에서 이 스크립트와 현재 사용자의 로케일에 일치하는 JSON 파일을 찾을 것을 압니다. 파일을 찾으면 스크립트가 실행되기 전에 번역을 삽입하고, JS __() 호출은 올바르게 해결됩니다. 전달하는 핸들은 등록된 스크립트와 정확히 일치해야 합니다. 핸들이 일치하지 않거나 누락된 경우가 번역이 조용히 실패하는 두 번째로 흔한 이유입니다.

아무도 예상하지 못하는 MD5 해시 파일명

거의 모든 사람을 헷갈리게 하는 세부 사항이 여기 있습니다. WordPress가 찾는 JSON 파일은 myplugin-fr_FR.json처럼 깔끔하게 이름 붙여지지 않습니다. 대신 스크립트 소스 경로의 MD5 해시로 이름이 지정됩니다:

파일명 패턴 해독하기

myplugin-fr_FR-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.json

패턴은 {textdomain}-{locale}-{md5}.json이며, 여기서 해시는 등록된 스크립트 파일(예: build/index.js)의 상대 경로에 대한 MD5입니다. WordPress는 런타임에 이 해시를 계산하여 올바른 스크립트에 대한 올바른 JSON을 찾습니다. 파일을 수동으로 이름 지정하면 WordPress가 찾지 못하고, 다른 파일명을 찾고 있을 뿐인데 시스템이 고장 났다고 맹세하게 될 것입니다.

해시를 직접 계산할 필요는 없습니다. WP-CLI i18n 명령어가 대신 처리해 주며, 이것이 바로 이 파일들을 수동으로 작성하는 대신 도구를 사용해야 하는 이유입니다. 하지만 해시가 존재한다는 사실을 이해하는 것이, languages/ 폴더에 JSON 파일이 있는데도 무시될 때 시간을 절약해 줍니다. 이는 스크립트 경로가 변경되어 파일명 해시가 불일치하는 경우가 거의 대부분입니다.

전체 워크플로: make-pot에서 make-json까지

좋은 소식은 기존에 사용하던 .po 파일에 번역을 그대로 유지한다는 것입니다. JSON은 최종적으로 생성되는 파생 아티팩트입니다. 'JS 문자열을 별도로 관리해야 하는가'에 대한 답은 '아니오'입니다. JS 문자열은 PHP 문자열과 동일한 .pot/.po 파일에 있으며, 하나의 추가 명령어가 JS 문자열을 JSON으로 분리해 줍니다.

네 단계 명령 파이프라인

전체 파이프라인은 다음과 같습니다:

# 1. Extract ALL translatable strings (PHP and JS) into one template
wp i18n make-pot . languages/myplugin.pot

# 2. Translate languages/myplugin-fr_FR.po as usual (Poedit, AI, etc.)

# 3. Compile the .mo for PHP strings (server-side, as always)
wp i18n make-mo languages/

# 4. Generate the MD5-hashed JSON files for JS strings
wp i18n make-json languages/ --no-purge

1단계의 make-pot은 .php 파일과 .js/.jsx 소스 모두를 스캔할 만큼 똑똑해서, 로케일당 하나의 .po 파일에 모든 것을 담습니다. 4단계의 make-json은 번역된 각 .po 파일을 읽어 자바스크립트 파일에서 가져온 항목을 찾아 스크립트당 하나의 올바르게 해시된 JSON 파일을 작성합니다. --no-purge 플래그는 JS 문자열을 .po 파일에도 유지하여 나중에 make-mo가 이들을 잃지 않도록 합니다. 이 플래그가 없으면 make-json이 .po에서 JS 항목을 제거하여 명령을 잘못된 순서로 실행하는 사람들을 놀라게 합니다.

생성된 JSON 파일은 Jed 형식 번역 세트와 유사합니다:

{
  "translation-revision-date": "2026-06-12 10:00+0000",
  "generator": "WP-CLI/2.x",
  "domain": "messages",
  "locale_data": {
    "messages": {
      "": { "domain": "messages", "lang": "fr_FR" },
      "Feature Box": [ "Bloc fonctionnalité" ],
      "Add Item": [ "Ajouter un élément" ]
    }
  }
}

WordPress는 locale_data를 읽어 스크립트가 실행되기 전에 @wordpress/i18n에 제공합니다. 이제 브라우저에서 __( 'Add Item', 'myplugin' )은 Ajouter un élément를 반환하며, 블록 편집기가 마침내 현지화됩니다.

i18next JSON과의 차이점

두 시스템 모두 JSON을 사용하고 자바스크립트를 대상으로 하며, 이러한 표면적인 유사성은 실제 혼란을 야기합니다. 이들은 상호 교환할 수 없습니다. WordPress 블록 편집기 JSON은 @wordpress/i18n이 사용하는 Gettext 파생, MD5 해시, 스크립트별 페이로드입니다. i18next JSON은 react-i18next 또는 next-intl이 사용하는 플랫 또는 중첩된 키-값 파일로, 자체 {{interpolation}} 구문과 복수형 키 규칙을 가지고 있습니다.

WordPress 외부에서 일반 React 또는 Next.js로 작업하는 경우, i18next 방식을 사용해야 합니다. 이에 대해서는 React 및 Next.js에서 i18next JSON 번역하기에서 다룹니다. WordPress 내에서는 위에 설명된 make-json 워크플로를 사용해야 합니다. 이들을 혼합하는 것은(예: 플랫 i18next 스타일 JSON을 수동으로 작성하고 wp_set_script_translations()가 이를 로드할 것으로 기대하는 것) 단순히 작동하지 않을 것입니다. WordPress는 임의의 키-값 쌍이 아닌 해시된 Jed 형식을 찾고 있기 때문입니다.

하나의 소스, 필요한 모든 형식

이 모든 것에서 취약한 부분은 중간에 있는 번역 단계입니다. .po 파일은 .mo(PHP)와 JSON(자바스크립트) 모두에 공급되므로, 하나의 잘못된 번역(예: 손상된 %s, 깨진 <strong> 태그, 이름이 변경된 복수형)은 두 출력 모두를 동시에 오염시킵니다. 그리고 JS 문자열은 브라우저에서 비동기적으로 로드되기 때문에, 구조적 오류는 종종 우아한 대체(fallback) 대신 빈 레이블이나 심각한 충돌로 나타납니다.

한 번의 업로드로 PHP 및 자바스크립트 모두 해결

이것이 바로 Gettext 구조를 이해하는 번역 파이프라인이 중요한 이유입니다. SimplePoTranslate는 하나의 .po 또는 .pot 소스를 사용하여 한 번의 업로드로 여러 형식의 깨끗하게 번역된 출력물(.po, .mo, .json, .php, .xliff)을 생성하므로, PHP 및 자바스크립트 계층을 위해 별도의 도구를 조합할 필요가 없습니다. SimplePoTranslate의 구문 잠금(Syntax Locking) 기능은 %s, %1$s, {count}, 인라인 HTML을 제자리에 유지하는데, 이는 깨진 자리표시자가 전체 편집기 패널을 작동 불능으로 만들 수 있는 블록 편집기 문자열에 특히 중요합니다. 단일 소스, 다중 출력 모델에 대해서는 하나의 파일 입력, 다섯 가지 형식 출력에서 더 자세히 다룹니다.

여전히 WordPress가 예상하는 해시 파일을 생성하기 위해 make-json을 실행해야 합니다. 이 단계는 WordPress에 특화되어 있으며 빌드에 남아 있습니다. 하지만 JS 문자열을 손상시킬 가능성이 가장 높은 번역 자체는 찾기 및 바꾸기 스크립트 대신 컨텍스트 인식 엔진에 의해 처리됩니다.

결론

블록 편집기가 영어로 남아있는 이유는 버그가 아니라 구조적인 문제입니다. WordPress JSON 번역은 .mo 파일과는 별개의 전달 시스템이며, 브라우저가 서버 측 Gettext 데이터를 읽을 수 없기 때문에 특별히 구축되었습니다. 자바스크립트 문자열이 wp i18n make-json에 의해 생성되고 wp_set_script_translations()로 연결된 스크립트별 MD5 해시 JSON을 필요로 한다는 것을 이해하면, 해결책은 기계적입니다. 문자열을 하나의 .po 파일에 유지하고, PHP용 .mo를 컴파일하고, JS용 make-json을 실행하십시오.

번역 단계를 올바르게 수행하면 두 가지 출력 모두 뒤따릅니다. 잘못 수행하면 오후 내내 빈 편집기 패널을 디버깅하게 될 것입니다.

깔끔한 하나의 소스에서 WordPress JSON 및 PHP 문자열을 번역할 준비가 되셨나요? SimplePoTranslate를 무료로 사용해보세요 — 신용카드 필요 없습니다. 무료 티어는 자리표시자 안전 구문 잠금(Syntax Locking) 기능으로 실제 .po 및 .pot 파일을 번역하므로, 블록 편집기 문자열이 올바르게 배포됩니다.