WordPress 테마 및 플러그인과의 WPML 호환성 구성 – 설정 및 사용자 정의 wpml-config.xml

이 페이지는 덜 인기 있는 테마 및 플러그인, WPML 호환성이 확보되기 전에 개발자가 배포한 최신 릴리스, 특정 증상이 나타나는 사이트를 위한 소수의 일반적인 도우미 등 나머지 경우를 위해 존재합니다. 대부분의 고객사는 이 페이지를 방문할 일이 없습니다. 이 페이지를 방문하게 된다면 주로 WPML 지원팀에서 특정 토글을 안내하거나 붙여넣을 wpml-config.xml를 지정했기 때문일 것입니다.

두 개의 설정 하위 페이지에서 호환성을 다루며, 이 페이지에서는 두 페이지를 모두 설명합니다. 설정 > 호환성에는 일반적인 증상에 대한 토글이 있습니다. 설정 > 사용자 정의 XML 구성은 고유한 wpml-config.xml를 작성하는 곳으로, 이 페이지의 후반부에서 설명합니다. 가장 일반적인 기본값(글 유형별, 택소노미별, 필드별 번역 기본 설정)에 대한 UI는 번역되는 항목과 번역되지 않는 항목에서 다루는 별도의 설정 페이지에 있습니다. 대부분의 고객사는 해당 UI를 사용하며 필요한 기능이 없을 때만 이 페이지를 방문합니다.

호환성 토글

WPML > 설정 > 호환성을 엽니다. 이 페이지에는 4개의 카드가 있습니다. 각 카드는 특정 호환성 문제 유형을 대상으로 합니다.

현지화 옵션 – 번역이 로드되지 않는 테마 및 플러그인용

테마나 플러그인에 자체 UI 번역(/languages/ 폴더의 .mo 파일)이 이미 포함되어 있지만 해당 번역이 사이트에 표시되지 않는 경우, 현지화 옵션 카드의 세 가지 토글을 사용하여 WPML이 번역을 찾아 적용하도록 도울 수 있습니다.

• load_textdomain를 사용하여 테마의 .mo 파일을 자동으로 로드합니다. WPML이 테마의 텍스트 도메인에 대해 load_textdomain()를 호출하도록 강제합니다. 테마의 번역이 디스크에 있지만 표시되지 않을 때 사용하세요.
• 텍스트 도메인을 입력하세요. 자동 감지된 텍스트 도메인을 재정의합니다. 일부 테마는 비표준 방식으로 텍스트 도메인을 등록하는데, 이 필드를 사용하면 명시적으로 지정할 수 있습니다.
• gettext 호출에서 문자열 리터럴을 사용하지 않을 때 테마 또는 플러그인 텍스트 도메인을 사용합니다. 리터럴 문자열 대신 변수 인수를 사용하여 __()를 호출하는 테마/플러그인을 위한 호환성 플래그입니다. WPML은 이를 자동 감지할 수 없으며, 이 토글을 사용하면 어쨌든 번역을 적용할 수 있습니다.

WPML 지원팀에서 이 페이지로 안내하는 경우 설정해야 할 토글과 텍스트 도메인을 알려줍니다.

테마를 다국어로 작동하게 만들기

다국어 기능을 위해 ID 조정. 단일 언어 가정을 하드코딩하는 테마(예: "특성 이미지 ID"를 한 번 저장하고 모든 언어에서 동일한 이미지를 사용하는 테마)를 위한 호환성 계층입니다.

대부분의 최신 WPML 호환 테마에서는 이 기능이 필요하지 않습니다. 오래되었거나 WPML을 잘 인식하지 못하는 테마의 경우 가끔 필요합니다. 콘텐츠 참조(이미지, 메뉴, 추천 항목)가 언어 간에 잘못 유출되는 경우 이 기능을 켜세요.

AJAX 작업을 위한 언어 필터링

AJAX 언어 필터링을 지원하기 위해 언어 쿠키를 저장합니다. 일부 플러그인은 AJAX를 사용하여 필터링된 제품 목록, AJAX 페이지 매김 글 목록, 입력 시 검색 결과 등의 콘텐츠를 가져옵니다. 언어 쿠키가 없으면 AJAX 엔드포인트는 어떤 언어로 응답해야 할지 알 수 없어 잘못된 언어 결과를 반환합니다.

프랑스어 페이지의 방문자가 AJAX로 로드된 섹션에서 영어 결과를 얻는 증상이 나타나면 쿠키를 켜세요. 확인란 하나로 전체 버그 클래스를 수정할 수 있습니다.

로그인 및 등록 페이지

로그인 및 등록 페이지 번역을 허용합니다. WordPress에 내장된 /wp-login.php 및 등록 화면은 WPML이 번역하는 일반 콘텐츠에 포함되지 않습니다. 이러한 페이지는 테마의 템플릿 체인 외부에 있습니다. 이 토글은 이러한 페이지를 WPML의 번역 가능한 페이지 세트에 추가합니다.

사이트가 nginx에서 실행되는 경우 이 토글을 사용하려면 서버 구성도 조정해야 합니다. 이 페이지는 정확한 구성 블록이 포함된 WPML의 nginx 가이드로 연결됩니다.

테마 및 플러그인 텍스트 – 설정은 여기에, 스캐너는 다른 곳에

두 가지 종류의 테마/플러그인 문자열 작업이 두 화면으로 나뉩니다.

• 이 페이지의 설정. 테마/플러그인에 이미 포함된 번역(load_textdomain, 텍스트 도메인 재정의, 비리터럴 gettext)에 대한 호환성을 처리합니다.
• 스캐너는 자체 화면에 있습니다. 아직 번역용으로 등록되지 않은 테마 및 플러그인 문자열을 찾아야 하는 경우 관리자 텍스트 번역 화면을 사용하세요. 이 화면은 번역의 문구 탭에 있는 “원하는 문구가 표시되지 않나요?” 섹션에서 접근할 수 있습니다.

전체 문자열 스캔 워크플로우는 문자열 번역을 참조하세요.

사용자 정의 wpml-config.xml

WPML 호환 테마 및 플러그인은 해당 필드, 글 유형, 택소노미, 숏코드, 메타 키 중 정확히 어떤 것을 번역할 수 있는지 WPML에 알려주는 wpml-config.xml 파일을 제공합니다. WPML은 활성화 시 이 파일을 읽습니다. 즉, 모든 주요 인기 테마 및 플러그인의 경우 추가 설정 없이 번역이 올바르게 작동합니다. 아무 작업도 수행할 필요가 없습니다.

테마나 플러그인과 함께 제공되는 wpml-config.xml가 사이트에 충분하지 않은 경우 고유한 파일을 작성할 수 있습니다. WPML은 테마나 플러그인에서 제공하는 파일 위에 이를 적용합니다.

고유한 wpml-config.xml을 작성하는 경우

세 가지 시나리오가 있습니다.

• 번역해야 하는 필드가 제공된 wpml-config.xml에 없습니다. 테마나 플러그인의 개발자가 사용자 정의 필드를 번역 가능한 것으로 선언하지 않았지만, 사이트에서 번역해야 하는 경우입니다.
• 필드의 기본값이 잘못되었습니다. 제공된 wpml-config.xml에서 항목을 복사로 표시했지만 번역을 원하거나 그 반대의 경우입니다.
• 사용자 정의 테마 또는 플러그인을 구축 중이며 코드에 wpml-config.xml 파일을 번들로 제공하는 대신 WPML의 설정 페이지에서 번역 동작을 선언하려는 경우입니다.

모든 경우에 WPML 지원팀에서 붙여넣을 정확한 wpml-config.xml과 함께 이 페이지로 안내할 수 있습니다. 대부분 지원팀 주도의 작업이며, 간혹 개발자 주도의 작업이기도 합니다.

테마 파일 대신 WPML 관리 화면에서 wpml-config.xml을 편집하는 이유

테마나 플러그인의 자체 wpml-config.xml를 직접 편집할 수도 있습니다. 하지만 다음에 테마나 플러그인을 업데이트할 때 해당 변경 사항이 손실됩니다. WPML > 설정 > 사용자 정의 XML 구성에 있는 WPML의 관리 화면 내 에디터는 테마나 플러그인에서 제공하는 파일 위에 wpml-config.xml을 계층화하여 업데이트 후에도 유지됩니다. 사이트별 조정을 위한 올바른 위치입니다.

wpml-config.xml의 형태

이 페이지는 XML 에디터입니다. <wpml-config>...</wpml-config> 블록을 붙여넣고 저장하면 WPML이 wpml-config.xml을 적용합니다.

숏코드를 번역 가능한 것으로 선언하는 최소한의 wpml-config.xml입니다.

<wpml-config>
  <shortcodes>
    <shortcode>
      <tag>add_to_cart_link</tag>
    </shortcode>
  </shortcodes>
</wpml-config>

일반적으로 선언하는 요소 유형은 다음과 같습니다.

• <custom-fields>. 사용자 정의 필드를 translate, copy, copy-once 또는 nothing로 표시합니다.
• <custom-types>. 사용자 정의 글 유형을 번역 가능한 것으로 선언합니다.
• <taxonomies>. 사용자 정의 택소노미를 번역 가능한 것으로 선언합니다.
• <shortcodes>. WPML이 콘텐츠를 번역해야 하는 숏코드를 나열합니다.
• <custom-term-fields>. 용어 메타데이터용입니다.

각 요소에는 고유한 속성(예: 사용자 정의 필드의 action="translate")이 있습니다. 전체 wpml-config.xml 참조(모든 요소, 모든 속성, 모든 허용 값)는 WPML 개발자 정보를 참조하세요.

실용적인 워크플로우

WPML 지원팀에서 붙여넣을 wpml-config.xml 블록을 제공하는 경우 다음을 수행합니다.

1. WPML > 설정 > 사용자 정의 XML 구성을 엽니다.
2. 기존 <wpml-config> 블록 안에 해당 XML을 붙여넣습니다(또는 전체 블록을 제공한 경우 내용을 바꿉니다).
3. 저장합니다.
4. WPML이 wpml-config.xml을 즉시 적용합니다. 번역 가능한 새 글 유형이나 필드를 선언하는 경우 항목이 설정 > 포스트 유형 번역 / 사용자 정의 필드 번역에 바로 표시됩니다.

사용자 정의 테마 또는 플러그인을 구축 중이며 코드와 함께 WPML 구성을 제공하려는 경우, 동일한 <wpml-config> 블록을 테마 또는 플러그인의 루트에 있는 wpml-config.xml 파일에 넣습니다. WPML은 활성화 시 이 파일을 읽습니다. 관리 화면 내 에디터는 사이트별 조정을 위한 것이며, 번들 파일은 테마/플러그인의 자체 기본값을 위한 것입니다.