본문으로 건너뛰기

WPML

Markdown으로 보기 ChatGPT에서 열기 (새 탭에서 열림) Claude에서 열기 (새 탭에서 열림)

WPML는 언어 구성 파일에 선언된 범위까지만 사용자 지정 블록의 속성을 번역합니다. Blockstudio는 모든 필드 값을 blockstudio.attributes 아래의 블록 주석에 저장하므로, 각 블록에는 WPML가 텍스트 필드와 첨부 ID를 찾도록 가리키는 항목이 필요합니다. wp bs wpml config 명령은 등록된 모든 블록의 항목을 작성합니다.

블록에 구성이 필요한 이유

WPML은 활성 테마와 각 활성 플러그인의 루트 폴더에 있는 wpml-config.xml라는 파일에서 구성을 읽습니다. 단일 파일인 필수 사용 플러그인의 경우 폴더 이름은 .php를 제외한 파일 이름입니다. 언어 구성 파일과 사용자 정의 Gutenberg 블록을 번역 가능하게 만들기를 참조하세요.

항목이 없는 블록은 WPML의 자동 문자열 감지에 맡겨집니다. 이 감지 기능은 블록의 모든 문자열 속성을 번역 대상으로 제공합니다. Blockstudio 블록에는 선택 값, 파일 참조, URL, CSS 클래스가 포함될 수 있습니다. 번역가는 실제 텍스트 옆에서 이러한 기술 값을 보게 되며, 선택 값이나 클래스가 번역되면 블록이 작동하지 않을 수 있습니다.

구성 생성

구성을 출력한 다음 블록이 포함된 테마 또는 플러그인의 루트 폴더에 저장합니다:

셸
wp bs wpml config > wp-content/themes/my-theme/wpml-config.xml

또는 명령어를 사용해 파일을 작성할 수 있습니다:

셸
wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml

텍스트 필드, 이미지, 링크, 반복 필드가 있는 블록:

JSON
{
  "name": "my-theme/cards",
  "title": "Cards",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "id": "gallery", "type": "files", "label": "Gallery", "multiple": true },
      {
        "id": "style",
        "type": "select",
        "label": "Style",
        "options": [
          { "value": "light", "label": "Light" },
          { "value": "dark", "label": "Dark" }
        ]
      },
      {
        "id": "cards",
        "type": "repeater",
        "label": "Cards",
        "attributes": [
          { "id": "title", "type": "text", "label": "Title" },
          { "id": "image", "type": "files", "label": "Image" },
          { "id": "link", "type": "link", "label": "Button" }
        ]
      }
    ]
  }
}

다음과 같이 됩니다:

XML
<wpml-config>
	<gutenberg-blocks>
		<!-- blockstudio:start -->
		<!-- Generated by wp bs wpml config. Run it again after changing block fields; edits between the markers are replaced. -->
		<gutenberg-block type="my-theme/cards" translate="1" label="Cards">
			<key name="blockstudio">
				<key name="attributes">
					<key name="heading" label="Heading" />
					<key name="gallery">
						<key name="*" type="post-ids" sub-type="attachment" />
					</key>
					<key name="cards">
						<key name="*">
							<key name="title" label="Cards: Title" />
							<key name="image" type="post-ids" sub-type="attachment" />
							<key name="link">
								<key name="title" label="Cards: Button: Link text" />
								<key name="url" type="link" label="Cards: Button: URL" />
							</key>
						</key>
					</key>
				</key>
			</key>
		</gutenberg-block>
		<!-- blockstudio:end -->
	</gutenberg-blocks>
</wpml-config>

style 값은 선언되지 않았으므로 WPML은 이 값을 변경 없이 번역에 복사합니다. gallery 및 image ID도 복사되며, 블록을 렌더링할 때 WPML가 각 ID를 페이지 언어에 해당하는 첨부 파일로 바꿉니다. 따라서 번역된 이미지에는 자체 대체 텍스트를 지정할 수 있습니다. 사용자 정의 Gutenberg 블록을 번역 가능하게 만들기에서 “블록의 ID 자동 변환”을 참조하세요. 첨부 파일에 번역이 없으면 WPML은 원래 ID를 유지합니다.

선언되는 항목

명령어는 등록된 블록을 읽으며, 이때 custom/ 필드와 블록 필드가 확장되고 재정의 및 속성 필터가 적용됩니다. Blockstudio 블록에 확장이 추가하는 필드가 포함됩니다. 확장 프로그램이 코어 블록이나 다른 플러그인의 블록에 추가하는 필드는 포함되지 않습니다. 해당 블록은 WPML 또는 자체 플러그인에서 구성을 가져오기 때문입니다.

필드 선언
text, textarea, richtext, wysiwyg 번역 가능한 텍스트입니다.
link 텍스트로서의 title와 type="link"이 포함된 url입니다. 따라서 WPML은 사용 가능한 번역이 있으면 링크를 해당 번역으로 바꿉니다.
files type="post-ids" 및 sub-type="attachment"이 적용된 저장된 첨부 파일 ID입니다. multiple의 경우 목록에 *이라는 수준을 지정합니다. 파일 하나를 선택했을 때 필드에 저장되는 단일 ID에도 이 수준이 적용됩니다.
repeater 모든 행에 적용되는 *이라는 수준과 행 필드의 선언입니다. 중첩 반복 필드도 같은 방식으로 처리됩니다.
group과 id이 있는 경우 그룹 ID를 키 접두사로 사용하는 그룹 필드입니다(그룹 cta의 필드 text에는 cta_text이 적용됩니다).
group에 id가 없는 경우, tabs 자체 수준 없이 필드가 선언됩니다.
true로 설정된 translate에 등록된 사용자 정의 필드 유형 text 필드와 마찬가지로 번역 가능한 텍스트입니다.
그 밖의 모든 내장 유형 선언되지 않습니다. WPML은 값을 변경 없이 복사합니다.

선언된 텍스트 필드가 없는 블록에는 translate="0"이 지정됩니다. 그러면 WPML은 모든 값을 복사하며 번역할 항목을 제공하지 않습니다. files 필드는 항목 내에서 계속 선언됩니다. translate의 설정과 관계없이 WPML이 첨부 파일 ID를 변환하기 때문입니다. 내부 블록은 일반적인 방식으로 번역됩니다.

선언되지 않는 항목:

  • hidden이 있는 필드. 편집기가 값을 작성하지 않기 때문입니다.
  • "translate": false이 있는 필드. 아래를 참조하세요.
  • translate를 true로 설정하지 않고 등록한 사용자 정의 필드 유형. 값에 텍스트가 들어 있는지는 필드 유형만 알 수 있으므로 각 유형에 대해 경고가 표시됩니다. 필드에 "translate": false을 명시적으로 설정하면 해당 필드의 경고도 억제됩니다. 아래를 참조하세요.
  • Blockstudio 필드가 아닌 블록의 기본 attributes에 선언된 속성.
  • 필드 유형이 서로 다른 저장 키. 아래를 참조하세요.

"translate": false을 설정하지 않으면 CSS 클래스와 같은 기술 값이 들어 있는 필드를 포함해 모든 텍스트 필드가 선언됩니다.

필드 제외

텍스트 필드에는 모든 언어에서 동일해야 하는 값이 들어갈 수 있습니다. 예를 들면 계정 핸들, 이메일 주소, 앵커, CSS 클래스입니다. WPML은 다른 텍스트와 마찬가지로 이를 번역 대상으로 제공하므로, 번역된 값이 블록을 작동하지 않게 할 수 있습니다. translate를 false로 설정하면 필드가 구성에서 제외되고, WPML은 해당 값을 번역에 변경 없이 복사합니다:

JSON
{
  "id": "account",
  "type": "text",
  "label": "Account handle",
  "translate": false
}

group, tabs 또는 repeater에서는 "translate": false이 중첩된 컨테이너를 포함해 내부의 모든 필드에 적용됩니다. 제외된 컨테이너에 속한 하위 필드는 "translate": true로 설정을 덮어쓸 수 없습니다. files 필드에서는 false이 첨부 파일 ID도 제외하므로 번역에서 원래 첨부 파일을 유지합니다.

translate을 생략하거나 true로 설정하면 기존 동작이 유지됩니다. 필드 유형이 처리 방식을 결정합니다. 이 설정으로 숨겨진 필드나 select와 같은 값 유형을 번역할 수 있게 되지는 않습니다. 이 옵션은 블록 및 확장 필드에 적용되며 편집기 컨트롤을 숨기거나 비활성화하지 않고 저장된 값도 변경하지 않습니다. 설정을 변경한 뒤 wp bs wpml config을 다시 실행하고 생성된 구성을 사용해 wpml-config.xml을 업데이트하세요.

각 키의 label는 필드 레이블이며, ID가 있는 상위 반복 필드와 그룹의 레이블이 앞에 붙습니다. WPML은 번역 편집기에 이를 필드 이름으로 표시합니다. link 필드의 두 키는 레이블에 Link text 및 URL를 추가합니다. 이 접미사는 사이트 언어로 번역되므로 번역가가 작업하는 로캘로 명령어를 실행하세요.

사용자 정의 필드 유형

일반 텍스트 문자열을 저장하는 필드 유형은 등록할 때 이를 지정합니다. 정의에서 translate을 true로 설정하세요. 이때 attribute는 string여야 합니다:

PHP
bs_register_field_type('acme/headline', [
  'attribute' => 'string',
  'translate' => true,
]);

그러면 명령은 해당 유형의 모든 필드를 번역 가능한 텍스트로 선언합니다. 필드에서 "translate": false을 설정해 제외할 수는 있습니다. 이 옵션이 없으면 이전과 같이 해당 유형의 필드는 제외되고 보고됩니다.

레이블 변경

필드 레이블은 블록 편집기용으로 작성되며 번역 편집기에서는 의미가 없는 “Image (optional)” 같은 힌트를 포함할 수 있습니다. blockstudio/wpml/config/label 필터는 각 레이블을 기록하기 전에 키의 컨텍스트와 함께 전달받습니다:

  • block: 블록 이름.
  • path: blockstudio.attributes 아래 필드의 저장 경로. 반복 필드의 각 행에는 * 수준이 있으며, 예를 들어 cards/*/link입니다.
  • field: 필드 정의.
  • parents: ID가 있는 상위 반복 필드와 그룹의 레이블.
  • part: 텍스트 필드의 text, 링크 필드의 두 키인 title 또는 url.
PHP
add_filter('blockstudio/wpml/config/label', function ($label, $context) {
  return str_replace(' (optional)', '', $label);
}, 10, 2);

키의 레이블을 제외하려면 빈 문자열을 반환하세요. 그러면 WPML 대신 블록 레이블이 표시됩니다. 문자열이 아닌 값을 반환하면 원래 레이블이 유지됩니다. 필터를 변경한 후 명령을 다시 실행하세요.

저장 키가 같은 필드

예를 들어 블록 필드와 확장 필드가 같은 id을 사용하거나, ID가 cta인 그룹의 필드 text과 ID가 cta_text인 필드가 같은 저장 키를 사용할 수 있습니다. 명령은 저장되는 값이 명확한 경우에만 해당 키를 선언합니다:

  • 반복 필드 행 바깥의 블록 필드끼리는 Blockstudio이 저장 키마다 하나의 속성을 등록하므로 나중 필드가 앞선 필드를 대체합니다. 유형과 관계없이 적용됩니다. 블록 확장의 필드도 같은 방식으로 동작합니다. 나중 필드나 나중에 등록된 확장의 필드가 앞선 필드를 대체합니다.
  • 같은 키를 사용하는 블록 필드와 확장 필드는 모두 적용됩니다. 블록 템플릿은 블록 필드 정의에 따른 값을 받고, 확장은 자체 필드를 적용합니다. 두 필드에 같은 선언이 필요한 경우 키는 한 번만 선언됩니다. 두 필드가 모두 텍스트 필드(text, textarea, richtext 또는 wysiwyg)인 경우, 둘 다 링크인 경우, 둘 다 files 필드인 경우(둘 중 하나에 multiple이 있으면 키에는 * 수준이 적용됨), 또는 select과 number처럼 어느 쪽도 선언되지 않은 경우입니다. 두 반복 필드는 행 안에서 필드별로 비교됩니다. 레이블은 블록 필드에서 가져옵니다.
  • 하나의 반복 필드 행에서 같은 id을 사용하는 두 필드도 모두 적용되며 같은 방식으로 비교됩니다.

유형이 다른 경우, 예를 들어 블록의 text 필드와 확장의 select 필드가 있으면 저장된 값은 이를 기록한 컨트롤에 따라 텍스트나 선택 옵션이 됩니다. 명령은 키를 선언하지 않고 다음 경고를 출력합니다:

셸
Warning: Not declared, the fields that store this key have different types: my-theme/cards: tone (text in the block, select in an extension)

필드 이름을 바꾸거나 두 필드의 유형을 같게 하면 키가 선언됩니다.

구성을 최신 상태로 유지

필드를 추가, 제거하거나 이름을 바꾼 후 명령을 다시 실행하고 업데이트된 파일을 테마 또는 플러그인과 함께 배포하세요. 7.7.5 이전에 만든 구성을 다시 생성해 첨부 파일 ID 선언을 포함하세요. 원본을 업데이트하면 기존 콘텐츠에도 번역할 새 필드가 표시됩니다. 위의 WPML 가이드에서 설명한 내용입니다.

--file을 사용하면 명령이 파일이 없을 때 파일을 생성합니다. 기존 파일에서는 <!-- blockstudio:start -->과 <!-- blockstudio:end --> 사이의 텍스트만 바꾸므로 다른 섹션과 다른 블록의 항목은 그대로 유지됩니다:

XML
<wpml-config>
	<custom-types>
		<custom-type translate="1">book</custom-type>
	</custom-types>
	<gutenberg-blocks>
		<gutenberg-block type="my-plugin/map" translate="1">
			<key name="caption" />
		</gutenberg-block>
		<!-- blockstudio:start -->
		<!-- blockstudio:end -->
	</gutenberg-blocks>
</wpml-config>

아직 마커가 없는 기존 파일을 사용하려면 gutenberg-blocks 요소 안에 두 마커 행을 한 번 추가하거나, 파일에 gutenberg-blocks 요소가 없다면 마커와 함께 해당 요소를 추가하세요. 마커가 없거나 결과가 유효한 구성이 되지 않으면 명령은 파일을 변경하지 않고 오류와 함께 종료됩니다.

Blockstudio 블록에 대해 직접 작성한 항목은 생성된 섹션이 블록을 포함하면 더 이상 필요하지 않습니다. 여기에는 기술 값을 숨기는 translate="0" 항목도 포함됩니다. 명령은 두 번 이상 선언된 모든 블록에 대해 경고하므로 이러한 항목을 제거할 수 있습니다.

번역 작업의 이미지 텍스트

WPML은 페이지에서 사용하는 이미지의 제목, 대체 텍스트, 캡션, 설명을 페이지 번역 작업에 포함합니다. 작업이 완료되면 WPML은 번역된 텍스트를 대상 언어의 첨부 파일에 기록하고, 아직 없으면 해당 첨부 파일을 생성합니다. 미디어 번역 방법을 참조하세요. WPML은 콘텐츠의 <img> 태그, 갤러리, 대표 이미지, 그리고 인식 가능한 블록에서 이미지를 찾습니다. Blockstudio 블록은 블록 주석에 첨부 파일 ID를 저장하므로 WPML은 해당 이미지를 찾지 못합니다.

WPML이 활성화되면 Blockstudio은 페이지 블록에서 필드가 저장하는 첨부 파일을 발견된 이미지 WPML에 추가합니다:

  • 숨겨진 항목을 포함한 files 필드와 media가 있는 attributes 필드. 블록 편집기가 미디어로 불러오는 것과 같은 필드입니다.
  • 그룹, 탭, 반복 필드 행, 내부 블록의 필드.
  • 확장의 필드. 핵심 블록과 다른 플러그인의 블록도 포함됩니다. 해당 값이 확장된 블록의 속성에 저장되기 때문입니다.

첨부 파일 ID가 아닌 값은 제외됩니다. 별도로 구성할 것은 없으며 wpml-config.xml도 관여하지 않습니다. WPML이 없으면 번역 작업을 위한 검색이 수행되지 않고 미디어 통합 클래스도 로드되지 않습니다.

이는 첨부 파일 ID 변환과는 별개입니다. 생성된 XML은 렌더링할 번역된 첨부 파일을 WPML에 알려 주고, 이 통합 기능은 번역 작업에 포함할 첨부 파일 텍스트를 알려 줍니다. 문자열 참조와 첨부 파일이 아닌 게시물의 ID는 미디어 작업에 추가되지 않습니다. 중첩 필드의 저장된 값은 렌더링할 때와 마찬가지로 Blockstudio 블록의 최상위 값보다 우선합니다.

이미지 텍스트 옵션 중 하나가 WPML > 설정 > 미디어 번역에서 활성화된 경우에만 텍스트가 작업에 포함됩니다. 옵션은 “이미지 텍스트 번역에 가장 적합한 옵션 자동 감지” 또는 “콘텐츠 번역 시 미디어 라이브러리 텍스트 번역”이며, 핵심 블록의 이미지에도 동일하게 적용됩니다.

Blockstudio는 필터 wpml_ids_of_media_used_in_post를 통해 이미지를 보고합니다. 이 필터는 PostWithMediaFiles의 게시물 미디어에 WPML를 적용합니다. 작업에서 이미지를 제외하려면 우선순위가 10보다 높은 동일 필터의 콜백에서 해당 ID를 제거하세요:

PHP
add_filter(
	'wpml_ids_of_media_used_in_post',
	function ( $ids ) {
		return array_values( array_diff( $ids, array( 42 ) ) );
	},
	20
);