WPML

번역을 위한 사용자 정의 페이지 빌더 위젯 등록

업데이트: 2026년 4월 24일

번역을 위해 사용자 정의 페이지 빌더 위젯을 등록하려면 wpml-config.xml 파일을 사용해야 합니다. 이 튜토리얼을 따라 사용 방법을 알아보세요.

이 가이드는 테마와 플러그인을 제작하거나 사이트에 사용자 정의 페이지 빌더 코드를 추가하는 개발자를 위한 것입니다.

타사 페이지 빌더를 사용 중이며 웹사이트의 사용자 정의 위젯을 번역할 수 없는 경우 WPML 지원팀에 문의하세요.

Elementor (새 탭에서 열림), Beaver Builder (새 탭에서 열림), SiteOrigin (새 탭에서 열림) 및 Cornerstone (새 탭에서 열림)과 같은 페이지 빌더에는 자체 위젯 제품군이 함께 제공됩니다. 이러한 기본 위젯은 WPML과 원활하게 작동합니다.

때로는 이러한 페이지 빌더나 다른 페이지 빌더와 함께 사용하기 위해 사용자 정의 위젯을 만들 수도 있습니다.

사용자 정의 위젯은 페이지 빌더에 번들로 제공되지 않는 고유한 추가 위젯을 의미합니다. 이러한 위젯은 개발 팀이나 타사 개발자가 만들거나 다른 플러그인 및 테마에서 제공될 수 있습니다.

또한 외부 개발자가 Elementor와 같은 페이지 빌더를 위해 특별히 개발한 애드온 플러그인에서 제공되는 모든 위젯도 사용자 정의 위젯에 포함됩니다.

사용자 정의 위젯을 번역용으로 등록해야 하는 경우

다음과 같은 경우 사용자 정의 위젯을 번역용으로 등록해야 합니다:

  • 원래 페이지 빌더에서 제공하지 않는 위젯인 경우
  • 다른 플러그인이나 테마를 통해 직접 만들어 추가한 경우
  • 팀이나 타사에서 내 WordPress 웹사이트 또는 특정 페이지 빌더를 위해 개발한 경우

과거에는 사용자 정의 위젯을 번역용으로 등록하는 가장 일반적인 방법이 사용자 정의 PHP 코드를 사용하는 것이었습니다. 이제 WPML의 구성 파일인 wpml-config.xml을 사용하여 위젯을 번역용으로 쉽게 등록할 수 있습니다.

WPML 4.9 이상에서 번역을 위한 사용자 정의 Elementor 위젯 등록

WPML 4.9 이상에서 WPML은 사용자 정의 Elementor 위젯을 자동으로 인식하고 번역 가능하게 만듭니다. 하지만 번역을 원하지 않는 문자열까지 등록될 수 있습니다.

따라서 이 페이지에 설명된 대로 wpml-config.xml 파일을 수동으로 구성하는 것을 강력히 권장합니다. 이를 통해 번역할 필드를 제어할 수 있습니다.

다국어 도구 플러그인을 사용하여 번역을 위한 사용자 정의 Elementor 위젯 및 Gutenberg 블록을 등록하는 방법

다국어 도구 플러그인에는 Elementor 및 Gutenberg 블록을 위한 WPML – Config Generator가 포함되어 있습니다. 이 기능을 사용하면 번역용으로 등록하려는 사용자 정의 Elementor 위젯이나 Gutenberg 블록을 페이지에 추가할 수 있습니다. 그러면 필요한 첫 번째 버전의 XML 코드가 자동으로 생성됩니다.

번역을 위한 사용자 정의 Elementor 위젯 등록 방법과 Gutenberg 블록을 번역 가능하게 만드는 방법을 알아보세요.

위젯의 등록 정보를 찾는 방법

wpml-config.xml 파일 내에 사용자 정의 위젯을 등록하려면 먼저 위젯의 유형 이름과 번역할 필드의 이름과 같은 기본 정보를 찾아야 합니다.

새 페이지에 위젯을 단독으로 추가하고 페이지를 저장하세요. Elementor는 페이지의 위젯을 _elementor_data 글 메타 필드에 저장하며, JSM Show Post Metadata (새 탭에서 열림)와 같은 플러그인은 페이지 에디터 하단의 메타박스에 해당 필드를 표시하므로 그곳에서 위젯의 데이터를 읽을 수 있습니다.

해당 데이터에서:

  • widgetType은 위젯의 name 속성에 사용할 이름입니다.
  • settings 아래의 키는 위젯의 필드입니다. title과 같이 번역할 텍스트가 포함된 키가 등록할 필드 이름입니다.
  • 반복자 필드에는 행의 배열이 포함됩니다. contents와 같이 해당 배열을 포함하는 키가 “items of” 이름입니다.
클래식 에디터에서 위젯 데이터 복사
WPML의 클래식 번역 에디터에 노출된 Elementor 위젯의 직렬화된 배열

이 정보를 얻은 후에는 실제로 위젯을 번역용으로 등록하는 과정을 진행할 수 있습니다.

작업을 확인하려면 번역 에디터에서 위젯을 사용하는 페이지를 여세요. 등록한 필드가 이름별로 표시되고 그 옆에 위젯의 텍스트가 나타납니다. 등록되지 않은 위젯은 작업에 아무런 내용도 추가하지 않으므로 텍스트가 전혀 나타나지 않는다면 등록이 적용되지 않은 것입니다.

단순 위젯 등록

다음 동영상에서는 단순 Elementor 위젯을 등록하는 예시를 안내합니다:

다음 예시는 단순 위젯을 등록하는 방법을 보여줍니다. 여기서 단순 위젯이란 반복자 필드가 없는 위젯을 의미합니다.

<wpml-config>
	<elementor-widgets>
		<widget name="heading">
			<conditions>
				<condition key="widgetType">heading</condition>
			</conditions>
			<fields>
				<field type="Heading" editor_type="LINE">title</field>
				<field type="Heading: Link URL" editor_type="LINK">link>url</field>
			</fields>
		</widget>
	</elementor-widgets>
</wpml-config>

주어진 예시의 구조를 살펴보겠습니다:

  1. <elementor-widgets> 태그로 시작합니다. 이는 WPML에 등록할 페이지 빌더 위젯을 알려줍니다. 다음 중 하나일 수 있습니다:
    • <elementor-widgets>: Elementor, Elementor PRO 또는 기타 Elementor 애드온을 사용하는 경우 사용해야 합니다.
    • <beaver-builder-widgets>: Beaver Builder Lite, 프리미엄 Beaver Builder 또는 기타 Beaver Builder 애드온을 사용하는 경우 사용해야 합니다.
    • <siteorigin-widgets>: SiteOrigin 페이지 빌더를 사용하는 경우 사용해야 합니다.
    • <cornerstone-widgets>: X 테마 또는 PRO 테마와 함께 제공되는 Cornerstone 페이지 빌더의 경우 사용해야 합니다.
  2. 위젯을 추가합니다:
    • <widget name="widget_name">에서 widget_name은 페이지 빌더에 위젯을 등록할 때 사용하는 이름입니다.
    • <conditions>(선택 사항): 조건 하에 위젯 이름과 동일한 키를 가진 조건을 추가합니다. 위젯 이름이 데이터의 위젯 키와 다를 때 사용할 수 있지만 일반적으로는 필요하지 않습니다.
  1. 위젯의 필드를 추가하고 <fields> 태그로 감쌉니다:
    • field: 필드의 ID입니다. 이는 Control_stack::add_control 함수를 통해 컨트롤을 추가할 때 사용하는 ID와 동일합니다.
    • type(선택 사항): 필드의 유형입니다. 이는 번역가가 어떤 필드가 번역되고 있는지 알 수 있도록 WPML 고급 번역 에디터 또는 클래식 번역 에디터에 표시되는 텍스트입니다.
    • editor_type(선택 사항): WPML 클래식 번역 에디터에서 사용되는 텍스트 필드의 유형입니다. 유효한 값은 LINE, AREA, LINK 및 VISUAL입니다. 누락된 경우 기본값은 LINE입니다.
    • key_of(선택 사항): <fields-in-item> 태그 내에 배열이 있는 <field> 태그에만 사용됩니다.

이러한 요소를 사용하여 원하는 수의 필드가 있는 단순 위젯을 등록할 수 있습니다.

글 또는 택소노미 ID가 있는 필드 등록

위 섹션에서 type 속성이 일반적으로 번역 에디터에 설명 텍스트를 표시하는 데 사용된다는 것을 배웠습니다.

하지만 위젯 필드에 글 ID나 택소노미 ID(예: 선택한 이미지, 관련 글 또는 선택한 카테고리)가 저장되는 경우 자동 변환을 트리거하는 특수 값을 사용합니다:

  • type="post-ids" – 글 ID가 포함된 필드용
  • type="term-ids" – 택소노미/용어 ID가 포함된 필드용

이러한 types 값을 사용하는 경우:

  • 필드가 번역 에디터에 나타나지 않습니다.
  • WPML이 ID를 해당 번역된 콘텐츠를 가리키도록 자동으로 변환합니다.
  • 단일 ID와 쉼표로 구분된 ID 목록이 모두 지원됩니다.

예시:

<wpml-config>
    <elementor-widgets>
        <widget name="the-widget-name">
            <fields>
                <field type="post-ids" sub-type="attachment">image_id</field>
                <field type="post-ids" sub-type="post">selected_posts</field>
                <field type="term-ids" sub-type="category">category_filter</field>
            </fields>
        </widget>
    </elementor-widgets>
</wpml-config>

이 예시에서 선택 사항인 sub-type 속성은 변환되는 정확한 글 유형 또는 택소노미를 지정합니다:

  • type="post-ids"의 경우: sub-type="attachment", sub-type="post", sub-type="page" 또는 사용자 정의 글 유형 슬러그를 사용합니다.
  • type="term-ids"의 경우: sub-type="category", sub-type="post_tag" 또는 사용자 정의 택소노미 슬러그를 사용합니다.

sub-type를 추가하면 콘텐츠 유형을 결정하기 위한 추가 데이터베이스 쿼리를 피할 수 있어 성능이 향상됩니다.

더 많은 예시는 Elementor의 구성 파일 (새 탭에서 열림)을 참조하고 post-ids를 검색하세요.

반복자 필드가 있는 위젯 등록

다음 동영상에서는 반복자 필드가 있는 고급 Elementor 위젯을 등록하는 예시를 안내합니다:

반복자 필드가 있는 위젯의 경우 필드를 <fields-in-item items_of="tabs"> 태그(여기서 tabs는 반복되는 필드가 있는 위젯의 이름)로 감싸야 합니다. 이 예시를 확인해 보세요:

<widget name="accordion">
	<fields-in-item items_of="tabs">
		<field type="Accordion: Title" editor_type="LINE">tab_title</field>
		<field type="Accordion: Content" editor_type="VISUAL">tab_content</field>
	</fields-in-item>
</widget>

경우에 따라 위젯에 여러 반복자 필드가 있을 수 있습니다. Ultimate Addons for Elementor의 Table 위젯의 다음 데이터 구조를 예로 들어 보겠습니다:

Ultimate Addons for Elementor의 Table 위젯 데이터 구조

이 위젯을 등록하려면 다음 예시를 참조하세요:

<widget name="uael-table">
	<fields-in-item items_of="table_content">
		<field type="The Cell text" editor_type="LINE">cell_text</field>
	</fields-in-item>
	<fields-in-item items_of="table_headings">
		<field type="The Heading text" editor_type="LINE">heading_text</field>
	</fields-in-item>
</widget>

단순 필드와 반복자 필드가 모두 있는 위젯 등록

참고로 위젯에는 fields 및 fields-in-item의 두 가지 유형이 모두 있을 수 있습니다. 두 가지를 모두 사용하는 위젯에 대한 이 예시를 확인해 보세요:

<widget name="price-table">
	<fields>
		<field type="Price Table: Heading" editor_type="LINE">heading</field>
		<!-- ... -->
	</fields>
	<fields-in-item items_of="features_list">
		<field type="Price table: text" editor_type="LINE">item_text</field>
	</fields-in-item>
</widget>

더 나은 구성을 위한 필드 그룹화

XML 구성의 명확성과 구성을 개선하기 위해 필드 레이블에 그룹 이름을 접두사로 추가할 수 있습니다. 핫스팟 위젯의 이 예시를 고려해 보세요:

<widget name="hotspot">
    <fields-in-item items_of="hotspot">
        <field type="Hotspot: Label">hotspot_label</field>
        <field type="Hotspot: URL" key_of="hotspot_link">url</field>
        <field type="Hotspot: Content" editor_type="VISUAL">hotspot_tooltip_content</field>
    </fields-in-item>
</widget>

여기서 핫스팟 위젯 내의 각 필드에는 Hotspot: 레이블이 접두사로 붙습니다. 이 접두사는 고급 번역 에디터에도 나타납니다. 위젯의 필드는 Hotspot 상자에 있으며 각각 고유한 레이블을 전달하므로 각 필드를 더 쉽게 식별하고 번역할 수 있습니다:

고급 번역 에디터의 핫스팟 위젯 필드
고급 번역 에디터의 핫스팟 위젯 필드

다른 유형의 페이지 빌더 콘텐츠 등록

문자열, 숏코드 등을 등록하는 방법에 대한 자세한 내용은 언어 구성 파일에 페이지 빌더 콘텐츠 등록 문서를 참조하세요.

추가 리소스

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

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

작성자:Amir