WordPress ACF 사용자 정의 필드 번역 - 필드 그룹, 반복자, 옵션 페이지

시작하기 전에

다음 플러그인을 설치하고 활성화하세요.

Advanced Custom Fields 또는 ACF Pro
WPML 및 WPML 문자열 번역
ACFML(이 페이지에서 다루는 애드온)

필드 그룹은 ACF에 이미 구성되어 있어야 합니다. 사후에 필드별 번역 기본 설정을 변경할 수 있으므로 작업 순서는 중요하지 않습니다. 필드 그룹을 설정한 다음 ACFML로 돌아오세요.

각 필드 그룹의 번역 모드 선택

번역 시 모든 ACF 필드 그룹이 동일하게 작동하는 것은 아닙니다. ACFML은 필드 그룹당 세 가지 모드를 제공하며, ACF > Field Groups의 Multilingual Setup 섹션에서 설정할 수 있습니다.

언어 간 동일한 필드

대부분의 ACF 사이트에서 사용하는 일반적인 설정입니다. 구조는 동일하게 유지하면서 필드 값을 각 언어로 번역합니다. Our Team(팀 소개) 페이지가 대표적인 예입니다. 팀 구성은 모든 언어에서 동일하므로 필드 구조는 그대로 유지되면서 각 팀원의 이름과 약력만 언어별로 번역됩니다. 원본 언어로 팀을 입력한 다음 WPML > 번역 > 대시보드를 통해 글을 번역에 보내면 번역된 값이 동일한 필드에 첨부되어 돌아옵니다.

언어 간 다른 필드

각 언어가 동일한 필드 그룹에서 근본적으로 다른 콘텐츠를 표시할 때 사용합니다. 지역화된 이벤트를 운영하는 회사가 대표적인 경우입니다. 영어 이벤트 페이지에는 영어권 대상 이벤트가 표시되고, 프랑스어 페이지에는 프랑스어권 대상 이벤트가 표시됩니다. 필드 그룹을 언어 간 다른 필드(Different fields across languages)로 설정한 다음, 현지화할 글을 엽니다 > 오른쪽 언어 상자에서 대상 언어의 더하기 아이콘을 클릭합니다 > 빈 사용자 정의 필드가 있는 임시글이 열립니다 > 언어별 값을 입력하고 발행합니다.

전문가 모드

혼합된 방식이 필요할 때 사용합니다. 일부 필드는 언어별로 번역하고, 다른 필드는 동일하게 유지하며, 또 다른 필드는 한 번 복사한 후 다르게 변경합니다. 필드 그룹 설정에서 전문가 모드(Expert Mode)를 선택하고 필드별로 기본 설정을 지정하세요. 혼합된 동작이 적용된 이벤트 예시: 제목과 설명은 번역(Translate)으로 설정하고 가격, 날짜, 주소는 복사(Copy)로 설정합니다.

각 ACF 필드 유형의 번역 기본 설정

필드 그룹의 모든 필드에는 다음 네 가지 번역 기본 설정 중 하나가 있습니다.

번역(Translate). 필드의 값이 언어별로 번역됩니다.
복사(Copy). 필드의 값이 언어 간에 동기화 상태를 유지합니다. 한 번 편집하면 전체에 적용됩니다.
한 번 복사(Copy Once). 필드의 값이 번역의 초기 바탕이 되며, 이후 각 언어 버전을 독립적으로 편집할 수 있습니다.
번역 안 함(Don't translate). 번역 단계에서 해당 필드를 무시합니다.

언어 간 동일한 필드 또는 언어 간 다른 필드를 선택하면 각 필드 유형에 따라 적절한 기본 설정이 지정됩니다. 아래 표는 이러한 기본값을 보여줍니다. 전문가 모드를 사용하여 필드별로 이 설정을 재정의하거나 acfml_field_group_mode_field_translation_preference 필터를 사용하여 사이트 전체의 필드 유형 기본값을 재정의할 수 있습니다(아래의 예외적인 경우를 위한 개발자 훅 참조).

리피터 및 유연한 콘텐츠 – 복사 또는 한 번 복사

리피터 및 유연한 콘텐츠 필드의 경우, 하위 필드 기본 설정이 적용되기 전에 두 가지 행 수준 동작 중 하나를 선택합니다.

복사(Copy). 모든 언어에서 레이아웃과 행 수가 동일합니다. 번역가는 동일한 행을 보게 되며, 하위 필드는 자체 기본 설정에 따라 번역됩니다.
한 번 복사(Copy Once). 초기 바탕이 설정된 후 각 언어는 다른 레이아웃과 다른 행 수를 가질 수 있습니다.

언어 간 구조가 동일한 경우(대부분의 경우) 복사를 선택하세요. 언어 버전이 구조적으로 달라지는 경우(예: 언어별로 다른 이벤트 목록) 한 번 복사를 선택하세요.

기본 필드

유형	언어 간 동일한 필드	언어 간 다른 필드
텍스트	번역	번역
텍스트 영역	번역	번역
숫자	복사	한 번 복사
범위	복사	한 번 복사
이메일	복사	한 번 복사
URL	복사	한 번 복사
비밀번호	복사	한 번 복사

콘텐츠 필드

유형	언어 간 동일한 필드	언어 간 다른 필드
이미지	복사	한 번 복사
파일	복사	한 번 복사
위지윅 에디터	번역	번역
oEmbed	복사	한 번 복사
갤러리	복사	한 번 복사

선택 필드

유형	언어 간 동일한 필드	언어 간 다른 필드
선택	복사	한 번 복사
체크박스	복사	한 번 복사
라디오 버튼	복사	한 번 복사
버튼 그룹	복사	한 번 복사
참 / 거짓	복사	한 번 복사

jQuery 필드

유형	언어 간 동일한 필드	언어 간 다른 필드
Google 지도	복사	한 번 복사
날짜 선택기	복사	한 번 복사
날짜 시간 선택기	복사	한 번 복사
시간 선택기	복사	한 번 복사
색상 선택기	복사	한 번 복사

레이아웃 필드

유형	언어 간 동일한 필드	언어 간 다른 필드
메시지	번역	번역
아코디언	복사	한 번 복사
탭	복사	한 번 복사
그룹	복사	한 번 복사
리피터	복사	한 번 복사
유연한 콘텐츠	복사	한 번 복사
복제	복사	한 번 복사

관계형 필드

유형	언어 간 동일한 필드	언어 간 다른 필드
링크	복사	한 번 복사
글 객체	복사	한 번 복사
페이지 링크	복사	한 번 복사
관계	복사	한 번 복사
택소노미	복사	한 번 복사
사용자	복사	한 번 복사

PHP 또는 JSON에 등록된 필드의 기본 설정 지정

PHP(acf_add_local_field_group()를 통해) 또는 ACF의 로컬 JSON 기능을 통해 등록된 ACF 필드 그룹은 관리 화면에서 관리하지 않으므로 관리자 UI에서 번역 기본 설정을 가져오지 않습니다. 필드를 등록하는 위치와 동일한 곳에 기본 설정을 지정하세요.

필드 그룹 정의의 각 필드에 wpml_cf_preferences 키를 추가합니다. 이 값은 네 가지 번역 기본 설정에 매핑되는 정수입니다. 0는 번역 안 함(WPML이 필드를 무시함), 1는 복사(값이 언어 간에 동기화 상태를 유지함), 2은 번역(값이 번역 단계를 거침), 3은 한 번 복사(값이 새 번역에 복사된 후 각 언어를 독립적으로 편집할 수 있음)를 나타냅니다.

간단한 예시:

acf_add_local_field_group( [
    'key'    => 'group_1',
    'title'  => 'My Group',
    'fields' => [
        [
            'key'                 => 'field_1',
            'label'               => 'Sub Title',
            'name'                => 'sub_title',
            'type'                => 'text',
            'wpml_cf_preferences' => 2, // Translate.
        ],
    ],
    // ...rest of the field-group config
] );

코드에서 필드를 정의한 후 관리 화면에서 인식할 수 있도록 기본 설정을 WPML에 동기화합니다.

ACF > Tools로 이동합니다.
Translate ACF Local JSON and PHP-Registered Fields로 스크롤합니다.
Sync Translation Preferences for Local Fields에서 Sync once now를 선택하고 적용을 클릭합니다.

WPML은 PHP 정의에서 기본 설정을 읽고 저장합니다. 동기화는 페이지를 로드할 때마다가 아니라 트리거할 때 한 번 실행됩니다.

ACF의 로컬 JSON 기능을 사용하여 사이트 간에 필드 그룹을 공유하는 경우 ACFML은 번역 기본 설정을 JSON 파일에 자동으로 기록합니다. 한 사이트에서 JSON 파일을 내보내고 다른 사이트에서 가져오면, 양쪽 모두에서 ACFML이 활성화되어 있을 때 대상 사이트가 기본 설정을 가져옵니다.

ACF 필드 레이블 번역

ACF 필드 레이블은 WordPress 에디터와 프런트엔드에서 각 사용자 정의 필드를 식별하는 이름입니다(예: 전화번호, 주소). 필드 값과는 별도로 번역되며, 글의 번역 작업이 아닌 WPML 문자열 번역에 있습니다.

필드 레이블을 번역에 보내려면 다음을 수행하세요.

WPML > 번역 > 대시보드를 엽니다.
ACF Field Group 섹션을 펼칩니다.
번역할 필드 그룹의 Field Group Labels 항목을 선택합니다.
번역 방식(PTC, 번역가 또는 직접 번역)을 선택하고 보냅니다.

번역이 완료되면 번역된 레이블이 프런트엔드에 자동으로 나타납니다.

ACF 필드 선택 항목 번역

선택 필드(선택, 체크박스, 라디오 버튼, 버튼 그룹)에는 고유한 옵션 레이블(예: 소 / 중 / 대)이 있습니다. 이 레이블 또한 글 번역 내부가 아니라 필드 레이블과 함께 존재합니다. 동일한 방법으로 보냅니다.

WPML > 번역 > 대시보드를 엽니다.
ACF Field Group 섹션을 펼칩니다.
선택 값을 번역할 필드 그룹을 선택합니다.
번역 방식을 선택하고 보냅니다.

ACF 옵션 페이지 번역

ACF 옵션 페이지(연락처 세부 정보, 헤더 설정, 푸터 링크와 같은 전역 설정 화면)는 글과 별개로 고유한 객체 유형으로 번역됩니다.

WPML > 번역 > 대시보드를 엽니다.
ACF Options 섹션을 펼칩니다.
번역할 옵션 페이지를 선택합니다.
번역 방식을 선택하고 보냅니다.

ACF가 해당 언어의 문맥에서 옵션을 읽을 때 각 언어의 옵션 페이지 값이 자동으로 나타납니다.

흔히 발생하는 문제

필드 레이블이 번역되지 않은 것처럼 보입니다. 글 번역이 아닌 문자열 번역에 있습니다. 대시보드에서 필드 그룹의 Field Group Labels 항목을 보냅니다(위의 ACF 필드 레이블 번역 참조).
선택 값이 번역되지 않은 것처럼 보입니다. 같은 상황입니다. 옵션 값이 포함되도록 대시보드의 ACF Field Group 섹션에서 필드 그룹을 보냅니다.
리피터 행의 동기화가 어긋납니다. 복사를 사용하면 행이 정렬된 상태로 유지되는데, 필드가 한 번 복사로 설정되어 있을 가능성이 높습니다. 필드 그룹을 엽니다 > 리피터 필드의 동작을 복사로 전환합니다.
조건부 논리가 예기치 않게 작동합니다. 제어 필드가 복사 또는 번역 안 함으로 설정된 경우, 조건부 동작은 모든 번역에서 원본 언어 값을 따릅니다. 언어별로 값이 달라야 하는 경우 제어 필드를 번역으로 설정하세요.
로컬 필드(PHP 등록)가 관리 화면에 설정된 번역 기본 설정을 무시합니다. 필드 그룹 정의 자체에 wpml_cf_preferences 키를 설정하고 ACF > Tools에서 동기화하세요. 절차는 위의 PHP 또는 JSON에 등록된 필드의 기본 설정 지정에 있습니다. ACFML 2.2.0(2026년 2월)에 전체 로컬 필드 지원이 추가되었으며, 이전 버전에는 이 부분에 제한이 있었습니다.

예외적인 경우를 위한 개발자 훅

프로그래밍 방식의 제어(특정 필드를 번역에서 제외, 사이트 전체의 필드 유형 기본값 재정의, 번역가에게서 주석 숨기기, 또는 글 번역 작업에서 필드 그룹 문자열 제외)를 위해 ACFML은 두 개의 필터와 네 개의 상수를 제공합니다. 코드 예시가 포함된 전체 참조는 ACFML 훅 및 상수 참조에 있습니다.