WordPress에서 ACF 사용자 정의 필드를 번역하는 방법 – 필드 그룹, 반복 필드, 옵션 페이지

시작하기 전에

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

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

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

각 필드 그룹에 대한 번역 옵션 선택

번역 시 모든 ACF 필드 그룹이 동일하게 작동하는 것은 아닙니다. ACFML은 각 필드 그룹에 대해 세 가지 번역 옵션을 제공합니다. 옵션을 선택하려면 다음을 수행하세요:

1. ACF → 필드 그룹으로 이동하여 필드 그룹을 편집하세요.
2. 다국어 설정 섹션의 이 필드 그룹의 번역 옵션 선택 아래에서 원하는 옵션의 선택을 클릭하세요.
3. 필드 그룹을 저장하세요.

ACFML은 사이트에 제안하는 옵션을 이 사이트에 권장됨으로 표시합니다. 나중에 다른 옵션을 선택하려면 옵션 변경을 클릭하세요. 이전 ACFML 버전에서는 처음 두 옵션을 언어 간 동일한 필드 및 언어 간 다른 필드라고 부릅니다.

모든 언어에서 동일한 콘텐츠 번역

대부분의 ACF 사이트에서 사용하는 일반적인 설정입니다. 모든 언어의 방문자가 동일한 페이지를 자신의 언어로 봅니다. 텍스트는 번역되며 레이아웃과 설정은 동일하게 유지됩니다. 우리 팀 페이지가 대표적인 예입니다. 팀은 모든 언어에서 동일하므로 각 팀원의 이름과 약력이 번역되고 필드 구조는 동일하게 유지됩니다. 기본 언어로 팀을 입력한 다음 WPML → 번역 → 대시보드에서 글을 번역에 보냅니다. 번역된 값이 동일한 필드로 다시 들어옵니다. 이 옵션은 자동 번역 및 모든 항목 번역과 함께 작동합니다.

각 언어에 고유한 콘텐츠가 있음

각 언어가 동일한 필드 그룹에서 다른 콘텐츠를 표시할 때 이 옵션을 사용하세요. 지역 이벤트를 운영하는 회사가 대표적인 예입니다. 영어 이벤트 페이지는 영어권 대상을 위한 이벤트를 표시하고, 프랑스어 페이지는 프랑스어권 대상을 위한 이벤트를 표시합니다. 필드는 원본의 복사본으로 시작합니다. 그 후 각 언어는 고유한 값을 유지합니다. WordPress 에디터에서 각 언어를 편집합니다: 글을 열고 언어 상자에서 대상 언어의 더하기 아이콘을 클릭한 다음 해당 언어의 값을 입력하고 발행합니다. 이후 WPML은 언어 버전을 동기화하지 않으며 자동 번역이 적용되지 않습니다.

전문가

일부 필드는 번역하고, 일부는 동일하게 유지하며, 일부는 한 번 복사한 후 각 언어에서 변경하는 등 혼합된 방식이 필요할 때 이 옵션을 사용하세요. 전문가를 선택하고 각 필드의 번역 기본 설정을 수동으로 설정합니다. 이벤트 예시에서 제목과 설명은 번역을 사용하고, 가격, 날짜, 주소는 복사를 사용합니다. ACFML은 새 필드 그룹에 이 옵션을 권장하지 않습니다. PHP 또는 로컬 JSON에 정의된 필드 그룹에는 번역 옵션이 없을 수 있습니다. 이 경우 사이트가 WPML 5.2로 업데이트되기 전에 필드 그룹이 존재하는 경우에만 전문가를 사용합니다.

각 ACF 필드 유형에 대한 번역 기본 설정

값을 저장하는 모든 필드에는 다음 네 가지 번역 기본 설정 중 하나가 있습니다:

• 번역. 방문자가 자신의 언어로 값을 봅니다. WPML이 번역으로 필드를 채웁니다. 번역 에디터에서 편집합니다.
• 복사. 모든 언어의 방문자가 원본과 정확히 동일한 내용을 봅니다. 다른 언어에서는 필드가 잠깁니다.
• 한 번 복사. 값은 원본의 복사본으로 시작합니다. 그 후 각 언어에서 수동으로 편집합니다. 번역에서 필드를 비우면 비어 있는 상태로 유지됩니다. WPML은 원본 값을 다시 복사하지 않습니다.
• 번역 안 함. 번역이 이 값 없이 시작됩니다. 각 언어에서 수동으로 채울 수 있습니다.

모든 언어에서 동일한 콘텐츠 번역 또는 각 언어에 고유한 콘텐츠가 있음을 선택하면 ACFML은 각 필드에 해당 필드 유형에 권장되는 기본 설정을 지정합니다. 아래 표는 이러한 권장 기본 설정을 보여줍니다. 하나의 필드에 다른 기본 설정을 지정하려면 전문가를 사용하세요. 전체 사이트에서 필드 유형의 권장 기본 설정을 변경하려면 acfml_field_group_mode_field_translation_preference 필터를 사용하세요(아래의 예외 상황을 위한 개발자 훅 참조).

탭, 아코디언, 메시지 및 구분선 필드는 값을 저장하지 않으므로 번역 기본 설정이 없습니다. 다른 플러그인의 필드 유형과 같이 표에 없는 필드 유형은 두 번역 옵션 모두에서 복사가 지정됩니다.

반복 필드, 유연한 콘텐츠, 그룹 및 복제 필드

이러한 필드에는 다른 필드가 포함됩니다. 컨테이너 필드의 권장 기본 설정은 복사 또는 한 번 복사입니다. ACFML은 컨테이너 필드 자체에 대해 번역을 제공하지 않습니다. 각 하위 필드에는 고유한 번역 기본 설정이 있습니다.

모든 언어에서 동일한 콘텐츠 번역을 사용하면 반복 필드 및 유연한 콘텐츠 필드의 행이 기본 언어와 동일한 순서로 유지됩니다. 전문가를 사용하거나 글에서 다른 옵션이 있는 필드 그룹을 사용하는 경우 글 에디터에 ACFML 번역 동기화 상자가 표시됩니다. 글에 번역이 있고 반복 필드 또는 유연한 콘텐츠 필드가 있는 경우 원본 글에 표시됩니다. 모든 언어에서 행을 정렬된 상태로 유지하려면 반복 필드 및 유연한 하위 필드를 기본 언어와 동일한 순서로 유지를 선택하세요.

기본 필드

콘텐츠 필드

선택 필드

jQuery 필드

레이아웃 필드

관계형 필드

링크 필드의 경우 번역에는 링크 텍스트와 URL이 포함됩니다. URL이 내 사이트의 페이지를 가리키고 이를 변경하지 않으면 WPML은 방문자의 언어로 페이지를 표시합니다.

URL 및 링크 필드

ACFML 5.0부터 URL 및 링크 필드는 기본적으로 번역 기본 설정을 사용합니다.

양방향 관계

ACF 6.2부터 관계, 포스트 객체, 분류 체계 및 사용자 필드는 양방향일 수 있습니다. 필드에서 대상을 선택하면 ACF가 대상의 페어링된 필드에 내 글을 추가합니다. 예를 들어, Dune이라는 책은 Author 필드를 Frank Herbert로 설정합니다. 그러면 ACF는 Frank Herbert의 Books 필드에 Dune을 추가합니다.

ACFML은 각 언어에서 쌍을 유지합니다:

• WPML이 필드를 번역으로 복사하면 ACFML은 동일한 언어의 대상을 가리키도록 필드를 지정합니다. 그런 다음 ACFML은 해당 대상의 쌍을 이루는 필드에 번역을 추가합니다. 스페인어 Dune에는 스페인어 Frank Herbert가 표시되고, 스페인어 Frank Herbert에는 스페인어 Dune이 나열됩니다.
• 필드에서 복사를 사용하고 원본 글에서 대상을 변경하면 WPML이 번역을 업데이트합니다. ACFML은 해당 언어의 새 대상에 번역을 추가하고 이전 대상에서는 이를 제거합니다.
• ACFML은 번역 언어의 대상만 변경합니다. 원본 언어의 글은 자체 쌍을 유지합니다.
• 대상에 아직 번역이 없을 때 번역은 원본 대상을 가리키며, ACFML은 원본 대상을 변경하지 않습니다. 나중에 대상을 번역하면 ACFML은 필드가 새 번역을 가리키도록 지정하고 쌍을 이루는 필드에 글을 추가합니다. 필드는 대상을 한 번만 나열합니다.
• 사용자는 번역이 없으므로 ACFML은 사용자의 쌍을 이루는 필드에 번역을 추가하지 않습니다. 해당 필드는 원본 글을 유지합니다. 필드에서 복사를 사용하지 않는 한, 다른 언어에서 ACFML은 해당 글의 번역을 표시합니다.

이는 해당 필드 유형의 권장 환경설정인 복사 및 한 번 복사 환경설정에 적용됩니다. WPML로 글을 복제할 때도 적용됩니다.

ACF 블록 번역

기본적으로 ACF 블록은 사용자 정의 필드가 아닌 글 콘텐츠 내의 블록 안에 필드 값을 저장합니다. ACFML은 동일한 번역 작업에서 글의 나머지 부분과 함께 이 값을 번역을 위해 전송합니다.

• 블록은 해당 블록을 위치 규칙으로 사용하는 필드 그룹의 번역 옵션과 필드 환경설정을 사용합니다.
• ACFML은 번역을 사용하는 필드만 전송합니다. 복사, 한 번 복사 또는 번역 안 함을 사용하는 필드는 원본 블록의 값을 유지합니다.
• 블록 내부의 반복 및 유연한 콘텐츠 필드도 번역되며 중첩된 경우에도 번역됩니다. 각 하위 필드는 자체 번역 환경설정을 사용합니다.
• block.json의 acf 섹션에 "usePostMeta": true가 있는 블록은 값을 블록이 아닌 글의 사용자 정의 필드로 저장합니다. 이러한 값은 필드 그룹의 번역 옵션 및 필드 환경설정을 통해 글의 다른 사용자 정의 필드와 동일하게 번역됩니다.
• 블록에서 사용하는 필드 그룹의 번역 환경설정을 변경하면 WPML에서 기존 번역을 업데이트할지 묻습니다. 확인하면 WPML은 해당 글의 번역을 업데이트가 필요한 것으로 표시합니다. 변경 사항을 적용하려면 번역을 위해 다시 전송하세요. 번역 안 함으로 변경해도 표시되지 않습니다.

block.json에 선언된 필드

ACF 6.8.1부터 블록은 block.json 파일의 acf.fields에 필드를 선언할 수 있습니다. ACF는 이러한 필드에 대한 필드 그룹을 생성하며 관리 화면에서 이 필드 그룹을 편집할 수 없습니다. ACFML은 PHP에 등록된 필드 그룹처럼 모든 언어에 동일한 콘텐츠 사용, 번역됨 옵션과 각 필드 유형에 권장되는 환경설정을 부여합니다.

전체 그룹에 다른 옵션을 사용하려면 block.json의 acf 섹션 또는 acf_register_block_type()에 acfml_field_group_mode을 추가하세요. 허용되는 값은 translation(모든 언어에 동일한 콘텐츠 사용, 번역됨), localization(각 언어에 고유한 콘텐츠 사용) 및 advanced(전문가)입니다. ACFML은 다른 모든 값을 무시합니다.

{
    "name": "acme/event-card",
    "title": "Event Card",
    "acf": {
        "mode": "preview",
        "acfml_field_group_mode": "localization",
        "fields": [ ... ]
    }
}

단일 필드의 환경설정을 설정하려면 해당 필드에 wpml_cf_preferences를 추가하세요. ACFML은 모든 옵션에서 이 환경설정을 유지합니다. 전문가 옵션을 사용하면 wpml_cf_preferences를 선언한 필드만 환경설정을 가져옵니다.

block.json이 옵션을 지정하지 않으면 ACFML은 해당 그룹을 처음 발견할 때 부여한 옵션을 저장하고 이후에도 이를 유지합니다. 이전 ACFML 버전에서 이러한 블록을 사용한 사이트의 경우 저장된 옵션은 전문가입니다.

PHP 또는 JSON으로 등록된 필드의 설정 지정

PHP(acf_add_local_field_group() 사용)에 등록되거나 ACF의 로컬 JSON 기능을 통해 등록된 ACF 필드 그룹은 관리 화면에서 이를 관리하지 않으므로 관리 화면에서 번역 설정을 가져오지 않습니다. 필드를 등록하는 것과 동일한 위치에서 설정을 지정하세요.

필드 그룹의 번역 옵션을 설정하려면 정의에 acfml_field_group_mode 키를 추가하고, 값으로 translation, localization 또는 advanced(Expert)을 지정하세요. 정의에 번역 옵션이 설정되지 않은 경우, ACFML은 그룹을 처음 볼 때 필드 그룹에 모든 언어에서 동일한 콘텐츠, 번역됨 옵션을 부여합니다. ACFML은 이 옵션을 저장하고 이후에도 유지합니다. 사이트가 WPML 5.2로 업데이트되기 전부터 존재하던 필드 그룹은 Expert를 유지합니다.

필드 그룹 정의의 각 필드에 wpml_cf_preferences 키를 추가하세요. 값은 네 가지 번역 설정에 매핑되는 정수입니다. 번역하지 않음(WPML이 필드를 무시함)은 0, 복사(값이 여러 언어에서 동기화된 상태로 유지됨)는 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에 동기화하세요.

1. ACF → Tools로 이동하세요.
2. Translate ACF Local JSON and PHP-Registered Fields로 스크롤하세요.
3. Sync Translation Preferences for Local Fields에서 Sync once now를 선택하고 적용을 클릭하세요.

WPML은 필드 정의에서 설정을 읽고 저장합니다. Sync once now는 한 번만 실행됩니다. 정의를 자주 변경하는 경우 대신 Sync on every request (may affect performance)를 선택하세요. 이 옵션은 모든 관리 화면 요청 시 동기화를 실행합니다.

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

ACF가 wp acf json import WP-CLI 명령으로 생성하거나 AI 도구용 Abilities API를 통해 생성하는 필드 그룹은 데이터베이스에 저장됩니다. ACFML은 이 필드 그룹에 모든 언어에서 동일한 콘텐츠, 번역됨 옵션과 각 필드 유형에 권장되는 설정을 부여합니다. 가져온 JSON에 이미 acfml_field_group_mode 키가 있는 경우 ACFML은 대신 해당 옵션을 사용합니다.

로컬 JSON 파일의 필드 그룹

ACF는 각 요청의 매우 이른 단계에서 acf-json 폴더의 필드 그룹을 로드합니다. WPML 5.2부터 ACFML은 이 필드 그룹을 동시에 읽습니다. 따라서 번역 설정을 동기화할 때 JSON 필드 그룹도 동기화에 포함됩니다. 그런 다음 WPML은 JSON 파일의 설정을 사용합니다.

JSON 파일에서 PHP와 동일한 값을 사용하여 각 필드에 wpml_cf_preferences을 추가하세요. 이 키는 필드 그룹의 번역 옵션과 관계없이 각 필드의 설정을 지정합니다. 예시에서는 Expert를 사용합니다.

{
    "key": "group_event",
    "title": "Event",
    "acfml_field_group_mode": "advanced",
    "fields": [
        {
            "key": "field_event_title",
            "label": "Event Title",
            "name": "event_title",
            "type": "text",
            "wpml_cf_preferences": 2
        },
        {
            "key": "field_event_price",
            "label": "Price",
            "name": "event_price",
            "type": "number",
            "wpml_cf_preferences": 1
        }
    ]
}

JSON 필드 그룹의 설정과 레이블을 WPML로 전송하려면 다음을 수행하세요.

1. ACF → Tools로 이동하세요.
2. Translate ACF Local JSON and PHP-Registered Fields로 스크롤하세요.
3. Sync Translation Preferences for Local Fields에서 Sync once now 또는 Sync on every request (may affect performance)를 선택하세요.
4. Register Labels for Translation에서 Register labels now를 선택하세요.
5. 적용을 클릭하세요.

결과를 확인하려면 WPML → 설정으로 이동하여 사용자 정의 필드 번역에서 필드를 찾으세요. 각 필드에는 JSON 파일의 설정이 표시됩니다. 또한 ACFML은 코드에만 존재하는 필드 그룹, 글 유형, 분류 체계 및 옵션 페이지의 레이블을 등록합니다. 즉, acf-json 폴더에 있거나 PHP에 등록된 항목입니다. 다른 필드 그룹의 레이블과 마찬가지로 이를 번역하세요(아래의 ACF 필드 레이블 번역 참조).

ACF 필드 레이블 번역

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

필드 레이블을 번역으로 전송하려면 다음을 수행하세요.

1. WPML → 번역 → 대시보드를 여세요.
2. ACF Field Group 섹션을 확장하세요.
3. 번역할 필드 그룹의 Field Group Labels 항목을 선택하세요.
4. 번역 방식(PTC, 번역가 또는 직접 번역)을 선택하고 전송하세요.

번역이 완료되면 번역된 레이블이 프런트엔드에 자동으로 표시됩니다.

필드 레이블 번역 중지

기본적으로 글의 번역 작업에는 필드 레이블이 포함되지 않습니다. 대시보드에서 Field Group Labels 항목을 보낼 때만 번역합니다. 보내지 않으면 ACF는 원본 레이블을 표시합니다. 번역이 존재할 때도 원본 레이블을 표시하려면 acfml_should_translate_acf_entity 필터를 사용하고 건너뛸 필드나 필드 그룹에 대해 false을 반환하세요. ACFML 훅 및 상수 참조에 예시가 있습니다.

ACF 필드 선택 항목 번역

선택 필드(Select, Checkbox, Radio Button, Button Group)에는 고유한 옵션 레이블(예: Small / Medium / Large)이 있습니다. 이 레이블도 글 번역 내부가 아니라 필드 레이블과 함께 존재합니다. 동일한 방법으로 보냅니다.

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

ACF 옵션 페이지 번역

ACF 옵션 페이지(Contact details, Header settings, Footer links와 같은 전역 설정 화면)는 글과 별도로 고유한 개체 유형으로 번역합니다.

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

ACF가 해당 언어의 컨텍스트에서 옵션을 읽을 때 각 언어의 옵션 페이지 값이 자동으로 표시됩니다.

옵션 페이지에 있는 필드 그룹의 번역 옵션에 따라 각 필드에 발생하는 일이 결정됩니다.

• 번역을 사용하는 필드는 번역 대시보드에서 보내는 ACF Options 항목에 들어갑니다. 번역이 완료되면 ACFML이 해당 언어의 옵션 페이지에 값을 씁니다. Repeater 및 Flexible Content 필드는 원본과 동일한 행을 갖습니다.
• 복사를 사용하는 필드는 모든 언어에서 원본 값을 가져옵니다. 원본을 저장하면 ACFML이 다른 언어를 업데이트합니다.
• 한 번 복사를 사용하는 필드는 원본의 복사본으로 시작합니다. 그 후에는 각 언어의 옵션 페이지에서 편집합니다.

언어별로 옵션이 다를 때는 각 언어에 고유한 콘텐츠가 있습니다를 사용하세요. 예를 들어, 옵션 페이지에 영어로는 영업 담당자가 3명, 스페인어로는 2명 나열되는 경우입니다. 옵션을 선택하려면 다른 필드 그룹과 마찬가지로 필드 그룹을 편집하세요.

완료된 번역을 변경하려면 WPML → 번역 → 번역 작업으로 이동하여 ACF Options 작업에서 편집을 클릭하세요. WPML → 문자열 번역에서도 번역된 값을 편집할 수 있습니다. 여기에서 번역을 저장하면 ACFML이 해당 언어의 옵션 페이지에 씁니다.

사이트의 기본 언어를 변경해도 기존 옵션 페이지 값은 작성했던 언어로 유지됩니다. ACF는 변경 전과 동일한 값을 읽습니다.

코드에서 get_field( 'my_field', 'option' )는 현재 언어의 값을 반환합니다. do_action( 'wpml_switch_language', 'fr' ) 이후에는 프랑스어 값을 반환합니다. 이는 사용자 정의 post_id가 있는 옵션 페이지에서도 작동합니다.

일반적인 문제

• 필드 레이블이 번역되지 않은 것처럼 보입니다. 이 레이블은 글 번역이 아니라 문자열 번역에 있습니다. 대시보드에서 필드 그룹의 Field Group Labels 항목을 보내세요(위의 ACF 필드 레이블 번역 참조).
• 선택 값이 번역되지 않은 것처럼 보입니다. 동일한 형태입니다. 옵션 값이 포함되도록 대시보드의 ACF Field Group 섹션에서 필드 그룹을 보내세요.
• 리피터 행의 동기화가 해제됩니다. 필드 그룹이 Expert를 사용할 가능성이 높습니다. 원본 글을 편집하고 ACFML Synchronise translations 상자에서 기본 언어와 동일한 순서로 리피터 및 플렉시블 하위 필드 유지를 선택한 다음 글을 업데이트하세요. 또는 필드 그룹을 모든 언어에서 동일한 콘텐츠, 번역됨으로 전환하세요.
• 조건부 로직이 예상과 다르게 작동합니다. 제어 필드가 복사 또는 번역 안 함으로 설정된 경우, 조건부 동작은 모든 번역에서 원본 언어의 값을 따릅니다. 언어별로 값이 달라야 한다면 제어 필드를 번역으로 설정하세요.
• 로컬 필드(PHP 등록)가 관리 화면에서 설정한 번역 기본 설정을 무시합니다. 필드 그룹 정의 자체에 wpml_cf_preferences 키를 설정하고 ACF → 도구에서 동기화하세요. 절차는 위의 PHP 또는 JSON에 등록된 필드의 기본 설정 지정에 있습니다.

예외 사례를 위한 개발자 훅

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