WPML

사용자 정의 Gutenberg 블록 번역 가능하게 만들기

업데이트: 2025년 6월 5일

개발한 사용자 정의 Gutenberg 블록 중 번역해야 할 블록을 지정하는 방법을 알아보세요. 다국어 도구 테스트 플러그인의 도움을 받아 wpml-config.xml 파일을 구성하여 이 작업을 수행할 수 있습니다.

이 가이드는 Gutenberg용 사용자 정의 블록을 직접 만드는 개발자를 위한 것입니다. 플러그인 개발자가 아닌 경우 Gutenberg 에디터로 생성된 콘텐츠를 번역하는 방법을 확인하세요.

시작하기

시작하려면 다음을 설치하고 활성화하세요.

  1. WPML 코어 플러그인
  2. WPML 문자열 번역
  3. 다국어 도구

다국어 도구 플러그인은 실제 서비스 중이거나 운영 사이트에서 사용해서는 안 됩니다. 테스트 용도로만 사용하세요.

번역용 Gutenberg 블록을 등록하기 위한 XML 코드 생성 및 테스트

1. 새 글이나 페이지를 만들고 등록할 Gutenberg 블록을 추가하세요. 번역 가능하게 만들 모든 필드에 테스트 콘텐츠를 추가한 다음 발행하세요.

WPML: Gutenberg Blocks 섹션으로 아래로 스크롤하여 생성된 XML 코드를 복사하세요.

검토를 위해 미리 생성된 XML 코드 복사
검토를 위해 미리 생성된 XML 코드 복사

중요: 자동으로 생성된 XML 코드를 그대로 사용해서는 안 됩니다. 사용자에게 제공하기 전에 테스트하고 편집해야 합니다. 다음 단계를 참조하세요.

2. WPML → 설정으로 이동하여 사용자 정의 XML 구성 탭 아래에 생성된 XML을 붙여넣으세요.

자동으로 생성된 코드를 철저히 검토하세요. 특정 값이 있는 구성 필드와 같이 번역할 필요가 없는 일부 필드는 제거해야 할 수도 있습니다.

준비가 되면 저장을 클릭하세요.

3. 발행한 페이지로 돌아가서 버튼의 텍스트나 제목을 편집하는 등 약간의 업데이트를 수행하세요.

언어 섹션 아래의 더하기 아이콘을 클릭하여 고급 번역 에디터를 엽니다. Gutenberg 블록의 필드가 에디터에 표시되며 번역할 수 있습니다.

WPML의 고급 번역 에디터에서 번역 가능한 Gutenberg 블록 확인
WPML의 고급 번역 에디터에서 번역 가능한 Gutenberg 블록 확인

번역 가능하게 만들 Gutenberg 블록을 등록한 후에는 언어 구성 파일을 만들 수 있습니다. 이미 있는 경우 편집하여 최종 XML 코드를 추가하기만 하면 됩니다.

번역 가능한 Gutenberg 블록 등록 예시

이미지 번역

다음 코드를 사용하여 표시되는 이미지가 있다고 가정해 보겠습니다.

번역이 필요한 이미지 예시
<!-- wp:image {"id":3} -->
<figure class="wp-block-image"><img src="http://example.com/wp-content/uploads/2018/07/figure-2.png" alt="Image alt text" class="wp-image-3"/><figcaption>Image Caption</figcaption></figure>
<!-- /wp:image -->

이 이미지의 figcaption 및 alt 속성 값을 번역하려고 합니다.

이를 수행하려면 wpml-config.xml에 다음 코드를 삽입해야 합니다.

Gutenberg 블록 번역을 위한 설정 예시
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/image" translate="1">
        <xpath>//figure/figcaption</xpath>
        <xpath>//figure/img/@alt</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

이것은 블록 API가 반환하는 값이므로 type은 wp:image가 아니라 core/image이라는 점에 유의하세요.

Gutenberg 블록 필드 중 어느 것이 링크인지 지정할 수 있습니다. 그러면 WPML은 사용 가능한 번역이 있는 경우 링크를 해당 번역으로 대체합니다.

Gutenberg 블록의 링크 번역
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/some-block" translate="1">
        <xpath type="link">//a/@href</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

블록 속성 번역

다음은 에디터 블록 정의 형식의 한 예시입니다.

에디터 블록 정의 형식
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <xpath label="My Block">//p</xpath>
        <key name="title" />
        <key name="foo">
            <key name="bar1" />
            <key name="bar2" />
        </key>
        <key name="/^[^_]\S+$/" search-method="regex" />
        <key name="something" search-method="wildcards" />
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

key 요소는 관리자 텍스트 / wp_options 구성에서 사용되는 것과 동일한 방식으로 사용할 수 있습니다. 즉, 부모 key 요소 안에 자식 key 요소를 가질 수도 있습니다.

label 속성을 사용하면 고급 번역 에디터에서 블록 요소 옆에 표시되는 선택적 사용자 정의 레이블을 추가할 수 있습니다. label 속성이 gutenberg-block 태그의 일부인 경우, 특정 레이블이 정의되지 않은 블록 요소의 대체 레이블로 사용됩니다.

대체 레이블 예시
<wpml-config>
    <gutenberg-blocks>
        <gutenberg-block type="my-plugin/mybutton" translate="1" label="My fallback block label">
            <xpath>//span</xpath>
            <xpath>//a@href</xpath>
        </gutenberg-block>
    </gutenberg-blocks>
</wpml-config>

search-method 속성은 다음 두 값 중 하나를 가질 수 있습니다.

  • wildcards (기본값)
  • regex

관리자 텍스트와 동일한 방식으로 와일드카드를 사용할 수 있습니다. 즉, name 속성에 별표(*)를 사용할 수 있습니다. 다음은 한 블록의 예시입니다.

블록 예시
<!-- wp:my-plugin/my-block
    {
        "myp": {
            "mypTitle":"The title",
            "mypContent":"The Content",
            "_mypSystem:"Meta attribute to not translate"
        }
    }
/-->

와일드카드를 사용하여 블록 정의를 설정할 수 있습니다.

와일드카드를 사용한 블록 정의
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
      <key name="myp">
          <key name="myp*" />
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

myp로 시작하는 유일한 속성이므로 이를 통해 “The title” 및 “The content”를 번역할 수 있습니다.

regex를 사용하면 name 속성에 정규식을 포함할 수 있습니다. 이는 복잡한 구성에 매우 유용할 수 있습니다. 다음은 한 블록의 예시입니다.

복잡한 구성 – 예시
<!-- wp:my-plugin/my-block
    {
        "data": {
            "title":"The title",
            "_title":"e980759463943209f6f1ae09a239e353",
            "content":"The Content",
            "_content":"1502a7b825dfe7b789c63830609f1701"
        }
    }
/-->

정규식을 사용하여 블록 정의를 설정할 수 있습니다.

정규식을 사용한 블록 정의
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

밑줄(_)로 시작하지 않는 유일한 속성이므로 이를 통해 “The title” 및 “The content”를 번역할 수 있습니다.

일부 블록 플러그인은 블록의 속성 내부에 URL 인코딩된 JSON 문자열로 데이터를 저장합니다. encoding 속성을 사용하면 문자열을 디코딩하고 번역을 위해 하위 키를 등록할 수 있습니다.

예를 들어 LazyBlocks 플러그인은 반복 필드 콘텐츠를 인코딩된 JSON 문자열로 저장합니다.

URL 인코딩된 JSON 문자열이 포함된 LazyBlocks 블록 예시
<!-- wp:lazyblock/testwpml {"name":"%5B%7B%22firstname%22:%22Shekhare%22,%22lastname%22:%22Bhandari%22%7D,%7B%22firstname%22:%22Compatibility%22,%22lastname%22:%22Escalation%22%7D%5D","blockId":"Z169b0O","blockUniqueClass":"lazyblock-testwpml-Z169b0O"} /-->

다음 XML 구성을 사용하여 firstname 및 lastname 하위 키를 등록할 수 있습니다.

블록의 속성 내부에 URL 인코딩된 JSON 문자열을 등록하는 예시
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="lazyblock/team" translate="1">
      <key name="name" encoding="json">
        <key name="*">
          <key name="firstname" />
          <key name="lastname" />
        </key>
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

WPML이 URL을 자동으로 번역할 수 있도록 Gutenberg 블록 속성을 링크로 선언할 수 있습니다.

다음은 클릭 가능한 링크가 있는 사용자 정의 Gutenberg 블록의 예시입니다.

<!-- wp:foo/link {"label":"Click here!","url":"https://example.com/some-page/"} /-->

label 및 url 속성을 번역 가능하게 만들려면 wpml-config.xml 파일에 다음을 추가하세요.

<gutenberg-block type="foo/link" translate="1">
	<key name="label" />
	<key name="url" type="link" />
</gutenberg-block>

이 구성에서 url 속성에 type="link"를 지정하면 WPML이 URL을 자동으로 번역할 수 있습니다.

블록 네임스페이스

블록 네임스페이스에 대한 전역 구성을 가질 수 있습니다.

블록 이름은 더 이상 정의에 필수적인 부분이 아닙니다.

네임스페이스의 모든 블록에 대해 블록 구성이 동일한 경우 다음과 같이 작성할 수 있습니다.

네임스페이스의 블록
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

블록에서 ID 자동 변환

ID 변환은 다용도로 사용되며 가능한 대부분의 ID 형식(단일 ID, ID 목록, 직렬화된 배열, JSON 인코딩된 배열)에 맞게 조정됩니다.

다음 블록을 고려해 보세요.

블록에서 ID 자동 변환 – 블록 예시
<!-- wp:foo/form {"ids":[27,28]} -->
<div class="wp-block-foo-form-wrap">
  <form class="foo-form" action="" method="post">
    <input type="hidden" name="foo_form_post_ids" value="27,28" />
    <input type="submit" />
  </form>
</div>
<!-- /wp:foo/form -->

아래와 같이 블록 속성 ID와 HTML 태그 속성 값 foo_form_post_ids를 글 ID로 선언할 수 있습니다.

블록 속성 ID 및 HTML 태그 속성 값
<gutenberg-block type="foo/form" translate="0">
  <key name="ids">
      <key name="*" type="post-ids" sub-type="post" />
  </key>
  <xpath type="post-ids" sub-type="post">//*[@name="foo_form_post_ids"]/@value</xpath>
</gutenberg-block>

블록은 아래와 같이 render_block_data 필터에서 가장 높은 우선순위로 변환됩니다.

render_block_data 필터에 의해 변환된 블록
<!-- wp:foo/form {"ids":[42,43]} -->
<div class="wp-block-foo-form-wrap">
    <form class="foo-form" action="" method="post">
        <input type="hidden" name="foo_form_post_ids" value="42,43" />
        <input type="submit" />
    </form>
</div>
<!-- /wp:foo/form -→

다음 구성 속성을 사용할 수 있습니다.

  • type – post-ids 또는 taxonomy-ids가 될 수 있습니다.
  • sub-type (선택 사항): 이미 알려진 경우 type의 특정 엔터티가 될 수 있습니다. 예를 들어 Product 사용자 정의 글 유형의 경우 product입니다. 정의되지 않은 경우 특정 엔터티를 추측합니다.

추가 리소스

wpml-config.xml 파일에 대해 자세히 알아보려면 언어 구성 파일 가이드를 방문하세요.

wpml-config.xml 파일을 사용하여 다른 요소를 사용자 정의하려면 다음 추가 가이드를 방문하세요.

작성자: Amir · 마지막 업데이트: 2025년 6월 5일