WPGraphQL로 다국어 콘텐츠를 쿼리하는 방법 – 언어 필터링 및 번역

시작하기 전에

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

• WPGraphQL(WPGraphQL 프로젝트의 오픈 소스 플러그인).
• WPML 및 WPML 문자열 번역.
• WPML GraphQL(이 페이지에서 다루는 애드온).

Advanced Custom Fields를 사용하는 경우:

• Advanced Custom Fields Multilingual(ACFML).
• WPGraphQL for Advanced Custom Fields(WPGraphQL 프로젝트 제공).

아래 쿼리에서 결과를 반환하려면 먼저 WPML에서 원본 콘텐츠를 번역해야 합니다. 모든 항목 자동 번역(WPML 5 기본값)을 켜면 콘텐츠를 발행할 때 백그라운드에서 번역이 생성됩니다. 수동으로 설정한 경우 WPML → 번역 → 대시보드에서 번역할 콘텐츠를 보내세요. 아래의 GraphQL 쿼리는 이렇게 번역된 글과 용어를 필터링하고 반환합니다.

GraphQL IDE – 쿼리 테스트 위치

WPGraphQL은 WordPress 관리 화면에 GraphQL → GraphQL IDE 화면을 추가합니다. IDE의 Query Composer는 WPML의 language 인수 및 translations 필드를 포함하여 사용 가능한 모든 필드를 나열하며, 운영 사이트에 대해 쿼리를 실행합니다. 프런트엔드 프레임워크에 연결하기 전에 여기에서 쿼리를 테스트하세요.

각 언어의 GraphQL 엔드포인트

WPGraphQL은 /graphql에서 응답합니다. language 인수가 없는 쿼리는 기본 언어의 콘텐츠를 반환합니다. 다른 언어의 콘텐츠를 가져오려면 쿼리에 where: { language: "es" }를 추가하세요.

언어별 콘텐츠 쿼리

글, 사용자 정의 글 유형, 분류 체계 용어, 메뉴, 메뉴 항목, 댓글 등 모든 목록 쿼리에 where: { language: "<code>" }를 추가하세요. 언어 코드는 WPML이 모든 곳에서 사용하는 코드(en, es, fr, pt-pt 등)와 동일합니다. 모든 언어의 콘텐츠를 한 번에 반환하려면 language: "all"을(를) 전달하세요.

query PostsES {
  posts(where: { language: "es" }) {
    nodes {
      slug
      uri
      categories {
        nodes { name }
      }
    }
  }
}

최상위 노드를 언어로 필터링하면 연결된 항목(카테고리, 태그, 사용자 정의 분류 체계)도 자동으로 동일한 언어를 따릅니다. 위의 쿼리는 추가 인수 없이 스페인어 카테고리가 포함된 스페인어 글을 반환합니다.

단일 쿼리로 노드의 모든 번역 가져오기

글 또는 분류 체계 쿼리에 translations 필드를 추가하면 동일한 페이로드에서 해당 노드의 다른 언어 버전을 반환합니다:

query PostsWithTranslations {
  posts(where: { language: "en" }) {
    nodes {
      slug
      uri
      language { code }
      translations {
        slug
        uri
        language { code }
      }
    }
  }
}

각 글은 영어 필드와 함께 다른 언어의 슬러그 및 URI 배열을 반환합니다. 이는 페이지 콘텐츠 옆에 렌더링되는 언어 전환기에서 사용하는 형태입니다. 즉, 한 번의 요청으로 방문자가 전환할 수 있는 모든 대안을 제공합니다.

모든 언어에서 ID 또는 슬러그로 특정 글 쿼리

번역된 단일 글을 (번역된 슬러그 또는 데이터베이스 ID로) 직접 가져오려면 idType와 함께 단수형 post 쿼리를 사용하세요:

query PostBySlug {
  post(id: "hola-mundo", idType: SLUG) {
    title
    slug
    uri
    language { code }
  }
}

query PostById {
  post(id: "2", idType: DATABASE_ID) {
    title
    slug
    uri
    language { code }
  }
}

두 쿼리 모두 프런트엔드에서 추가 필터링 없이 번역된 글(제목, 슬러그, URI)을 반환합니다.

다국어 메뉴

동일한 where: { language } 인수를 사용하여 언어별로 메뉴와 메뉴 항목을 쿼리하세요. 테마 메뉴 위치의 항목을 가져오려면 위치도 추가하세요:

query NavES {
  menuItems(where: { language: "es", location: PRIMARY }) {
    nodes {
      label
      url
      path
    }
  }
}

특정 언어의 메뉴를 나열하려면 menus 쿼리를 사용하세요:

query MenusES {
  menus(where: { language: "es" }) {
    nodes {
      name
      locations
    }
  }
}

각 메뉴 항목의 label 및 url은 쿼리된 언어로 반환됩니다. 번역된 글로 연결되는 메뉴 항목은 자동으로 번역된 URI로 확인됩니다. 단수형 menu 쿼리에는 language 인수가 없으므로 menus 또는 menuItems를 사용하여 언어를 선택하세요.

설치된 언어 – 언어 전환기용

(단일 글과 독립적인) 전역 언어 전환기의 경우 languages 및 defaultLanguage 쿼리를 사용하여 사이트의 모든 언어를 나열하세요:

query SiteLanguages {
  languages {
    code
    country_flag_url
    default_locale
    native_name
    translated_name
    url
  }
  defaultLanguage {
    code
    native_name
  }
}

국기 URL, 고유 명칭, 번역된 이름 및 해당 언어의 홈 URL과 함께 활성 언어당 하나의 노드를 반환합니다. 이는 언어 목록을 하드코딩하지 않고도 국기 및 레이블 전환기를 렌더링하기에 충분한 데이터입니다.

언어별 ACF 사용자 정의 필드 쿼리

ACFML 및 WPGraphQL for ACF가 활성화된 경우 글 또는 사용자 정의 글 유형의 ACF 필드는 해당 글에 저장된 값을 반환합니다. 각 번역에는 고유한 값이 있으므로 필요한 언어로 글을 쿼리하세요. 추가 인수는 필요하지 않습니다.

단일 글에 연결되지 않은 ACF Options Pages의 경우 Options Page 쿼리에 language 인수를 추가하세요:

query Settings {
  myOptionPage(language: "de") {
    addressFieldGroup {
      addressTitle
      repeaterAddressDetails { addressDetails }
    }
  }
}

이 인수는 사이트의 활성 언어 중 하나와 일치하는 언어 코드를 필요로 합니다.

WPGraphQL for ACF 3.0.0부터는 해당 페이지에 대해 show_in_graphql을 켤 때만 옵션 페이지가 GraphQL 스키마에 포함됩니다. 이 설정이 없으면 옵션 페이지 쿼리와 language 인수가 존재하지 않습니다. 코드에 옵션 페이지를 등록하는 경우 거기에 설정을 추가하세요:

acf_add_options_page( array(
  'page_title'         => 'Site Settings',
  'menu_slug'          => 'site-settings',
  'show_in_graphql'    => true,
  'graphql_field_name' => 'siteSettings',
) );

번역된 작성자 세부 정보

WPML GraphQL은 사용자의 번역된 firstName, lastName, nickname 및 description을(를) 반환합니다. 이를 번역하려면 다음을 수행하세요:

1. WPML → 문자열 번역 페이지로 이동하세요.
2. Translate User properties 옵션에서 사용자 역할을 선택하고 저장하세요.
3. Authors 도메인의 문자열을 번역하세요.

알려진 제한 사항 및 임시 해결 방법

• 일부 쿼리 형태의 번역된 URI. URI(contentNode(id: "/de/some-slug/", idType: URI))로 번역된 글을 가져올 때 반환된 URI가 해당 언어로 발행된 내용과 일치하는지 확인하세요. 일부 쿼리 형태는 일관되지 않은 경로를 반환합니다. 라우팅에 연결하기 전에 GraphQL IDE에서 테스트하세요.
• language 인수가 없는 ACF Options Pages는 기본 언어로 대체됩니다. 다국어 사이트에서 Options Page 쿼리에는 항상 language을(를) 전달하세요.

여기에 나열되지 않은 통합 문제가 발생하는 경우 WPML 지원 팀에서 WPGraphQL 스택의 WPML 측면을 연중무휴 24시간 지원합니다.