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

사용자 정의 페이지 빌더 위젯을 번역 가능한 항목으로 등록하려면 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 블록을 등록하는 방법

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

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

wpml-config.xml 파일 내에 사용자 정의 위젯을 등록하려면 먼저 위젯에 대한 기본 정보를 찾아야 합니다.

JSM Show Post Metadata와 같은 플러그인을 사용하면 이 정보를 쉽게 얻을 수 있습니다. 이 플러그인은 글 편집 페이지 하단의 메타박스에 글 메타데이터와 직렬화되지 않은 값을 표시합니다.

또는 다음 단계에 따라 이 정보를 얻을 수 있습니다.

WPML → 설정 페이지로 이동하여 사용자 정의 필드 번역 섹션으로 스크롤한 다음 시스템 필드 표시 링크를 클릭하세요.
_elementor_data 사용자 정의 필드를 번역으로 설정하세요.
새 페이지를 만들고 등록하려는 Elementor 위젯만 추가하세요. 페이지를 저장하세요.
WPML → 설정으로 이동하여 번역 에디터 섹션에서 클래식 번역 에디터 옵션을 일시적으로 활성화하세요.
클래식 번역 에디터를 사용하여 3단계에서 만든 페이지를 번역해 보면 다음과 같은 직렬화된 배열을 볼 수 있습니다.

클래식 에디터에서 위젯 데이터 복사하기 — WPML의 클래식 번역 에디터에 노출된 Elementor 위젯의 직렬화된 배열

직렬화된 배열의 내용을 복사하세요.
선호하는 역직렬화 도구를 사용하여 위젯이 콘텐츠를 출력하는 방식을 더 잘 확인하세요. 이 예시에서는 Unserialize 사이트를 사용했습니다.

표시되는 배열의 내용에 대한 설명은 다음과 같습니다.

[widgetType]에는 위젯 태그의 name 속성에 삽입된 이름이 포함됩니다.
실제 필드는 배열 내부에 있으며 배열의 첫 번째 요소 내용을 가져오는 [0]을 검색하여 찾을 수 있습니다.
field 값은 필드 이름이 포함될 대괄호 안의 이름입니다. 예: [title] => this is a field title. 이 경우 필요한 텍스트는 “title”입니다.
“Items of”는 배열을 만드는 요소에서 값을 가져옵니다. 예: [contents]=> array. 이 경우 필요한 텍스트는 “contents”입니다.

이 정보를 얻은 후에는 실제로 위젯을 번역 가능한 항목으로 등록하는 작업을 진행할 수 있습니다.

단순한 위젯 등록

다음 동영상은 단순한 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>

제공된 예시의 구조를 살펴보겠습니다.

<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 페이지 빌더에 이를 사용해야 합니다.
위젯을 추가합니다.
- <widget name="widget_name">에서 widget_name은 페이지 빌더에 위젯을 등록하는 데 사용되는 이름입니다.
- <conditions> (선택 사항): conditions 아래에 위젯 이름과 동일한 키를 사용하여 조건을 추가합니다. 데이터의 위젯 키와 위젯 이름이 다를 때 사용할 수 있지만 일반적으로 필요하지 않습니다.

위젯의 필드를 추가하고 <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 위젯을 등록하는 예시를 보여줍니다.

A hotspot widget's fields in the Advanced Translation Editor

반복기 필드가 있는 위젯의 경우 필드를 <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: 레이블이 접두사로 붙습니다. 이 접두사는 고급 번역 에디터에도 표시되므로 각 필드를 더 쉽게 식별하고 번역할 수 있습니다.

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

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

추가 리소스

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

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

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