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 필드를 포함하여 사용 가능한 모든 필드를 나열하고 라이브 사이트에서 쿼리를 실행합니다. 프런트엔드 프레임워크에 연결하기 전에 여기에서 쿼리를 테스트하세요.

언어별 콘텐츠 쿼리

글, 사용자 정의 글 유형, 택소노미 용어, 메뉴, 메뉴 항목, 댓글 등 모든 목록 쿼리에 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)을 반환합니다.

다국어 메뉴

동일한 language 인수를 사용하여 언어별로 메뉴와 메뉴 항목을 쿼리합니다.

query NavES {
  menu(language: "es", id: "primary", idType: SLUG) {
    menuItems {
      nodes {
        label
        url
        path
      }
    }
  }
}

각 메뉴 항목의 label 및 url는 쿼리된 언어로 반환됩니다. 번역된 글로 연결되는 메뉴 항목은 자동으로 번역된 URI로 확인됩니다. 이 지원은 WPML GraphQL 1.1.0에 추가되었습니다.

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

전역 언어 전환기(단일 글과 독립적)의 경우 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 }
    }
  }
}

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

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

• 작성자 및 사용자 메타데이터는 번역된 값을 반환하지 않습니다. 언어별로 작성자 약력을 표시하려면 번역된 약력을 사용자의 ACF 필드에 저장하고 대신 해당 필드를 쿼리하세요.
• 일부 쿼리 형태의 번역된 URI. URI(contentNode(id: "/de/some-slug/", idType: URI))로 번역된 글을 가져올 때, 반환된 URI가 해당 언어로 게시된 항목과 일치하는지 확인하세요. 일부 쿼리 형태는 일치하지 않는 경로를 반환할 수 있습니다. 라우팅에 연결하기 전에 GraphQL IDE에서 테스트하세요.
• language 인수가 없는 ACF Options Pages는 기본 언어로 대체됩니다. 다국어 사이트의 Options Page 쿼리에는 항상 language을 전달하세요.

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