Cómo consultar contenido multilingüe con WPGraphQL: filtrado de idiomas y traducciones

Antes de empezar

Instale y active estos plugins:

• WPGraphQL (el plugin de código abierto del proyecto WPGraphQL).
• WPML y WPML Traducción de cadenas.
• WPML GraphQL (el complemento que trata esta página).

Si también utiliza Advanced Custom Fields:

• Advanced Custom Fields Multilingual (ACFML).
• WPGraphQL for Advanced Custom Fields (del proyecto WPGraphQL).

Su contenido de origen debe estar traducido en WPML antes de que las consultas siguientes puedan devolver algo. Con la opción Traducir todo automáticamente activada (el valor predeterminado en WPML 5), las traducciones se generan en segundo plano a medida que publica contenido. Para una configuración manual, envíe el contenido a traducir desde WPML → Traducciones → Escritorio. Las entradas y los términos traducidos son lo que las consultas GraphQL a continuación filtran y devuelven.

El IDE de GraphQL: dónde probar las consultas

WPGraphQL añade una pantalla GraphQL → GraphQL IDE al panel de administración de WordPress. El Query Composer del IDE enumera todos los campos disponibles, incluidos el argumento language y el campo translations de WPML, y ejecuta consultas en su sitio en vivo. Pruebe las consultas allí antes de integrarlas en su framework de front-end.

El endpoint de GraphQL para cada idioma

WPGraphQL responde en /graphql. Una consulta sin un argumento language devuelve el contenido en su idioma predeterminado. Para obtener contenido en otro idioma, añada where: { language: "es" } a la consulta.

Consultar contenido por idioma

Añada where: { language: "<code>" } a cualquier consulta de lista: entradas, tipos de contenido personalizado, términos de taxonomía, menús, elementos de menú o comentarios. El código de idioma es el mismo que WPML utiliza en todas partes (en, es, fr, pt-pt, etc.). Pase language: "all" para devolver contenido de todos los idiomas a la vez.

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

Cuando un nodo de nivel superior se filtra por idioma, los elementos conectados (categorías, etiquetas, taxonomías personalizadas) siguen automáticamente el mismo idioma. La consulta anterior devuelve entradas en español con categorías en español, sin necesidad de argumentos adicionales.

Obtener todas las traducciones de un nodo en una sola consulta

Añada el campo translations a cualquier consulta de entrada o taxonomía para devolver las versiones en otros idiomas del nodo en la misma respuesta:

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

Cada entrada se devuelve con sus campos en inglés más un array con sus slugs y URI en otros idiomas. Esta es la estructura que utiliza un selector de idiomas mostrado junto al contenido de la página: una sola petición con todas las alternativas a las que el visitante puede cambiar.

Consultar una entrada específica por ID o slug en cualquier idioma

Para obtener una única entrada traducida directamente (por su slug traducido o por su ID de base de datos), utilice la consulta singular post con idType:

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 }
  }
}

Ambas consultas devuelven la entrada traducida (título, slug, URI) sin necesidad de más filtrado en el front-end.

Menús multilingües

Consulte menús y elementos de menú por idioma con el mismo argumento where: { language }. Para obtener los elementos de una ubicación del menú del tema, añada también la ubicación:

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

Para listar los menús de un idioma, utilice la consulta menus:

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

El label y url de cada elemento del menú se devuelven en el idioma consultado. Los elementos del menú que enlazan a entradas traducidas se resuelven automáticamente a la URI traducida. La consulta singular menu no tiene argumento language, así que utilice menus o menuItems para elegir el idioma.

Idiomas instalados: para un selector de idiomas

Para un selector de idiomas global (independiente de cualquier entrada), utilice las consultas languages y defaultLanguage para listar todos los idiomas del sitio:

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

Devuelve un nodo por cada idioma activo con la URL de la bandera, el nombre nativo, el nombre traducido y la URL de inicio del idioma. Estos son datos suficientes para mostrar un selector con bandera y etiqueta sin tener que programar la lista de idiomas de forma rígida.

Consultar campos personalizados de ACF por idioma

Cuando ACFML y WPGraphQL for ACF están activos, los campos de ACF en una entrada o tipo de contenido personalizado devuelven los valores guardados en esa entrada. Cada traducción tiene sus propios valores, por lo que debe consultar la entrada en el idioma que necesite. No se necesitan argumentos adicionales.

Para las páginas de opciones de ACF, que no están vinculadas a una sola entrada, añada el argumento language a la consulta de la página de opciones:

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

El argumento espera un código de idioma que coincida con uno de los idiomas activos de su sitio.

Desde WPGraphQL for ACF 3.0.0, una página de opciones solo aparece en el esquema de GraphQL cuando activa show_in_graphql para ella. Si no lo hace, la consulta de la página de opciones y su argumento language no existirán. Si registra la página de opciones por código, añada la configuración allí:

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

Detalles de autor traducidos

WPML GraphQL devuelve firstName, lastName, nickname y description traducidos de los usuarios. Para traducirlos:

1. Vaya a la página WPML → Traducción de cadenas.
2. En la opción Translate User properties, seleccione los roles de usuario y guarde.
3. Traduzca las cadenas en el dominio Authors.

Limitaciones conocidas y soluciones alternativas

• URI traducidas en algunas formas de consulta. Al obtener una entrada traducida por URI (contentNode(id: "/de/some-slug/", idType: URI)), verifique que la URI devuelta coincida con lo publicado en el idioma: algunas formas de consulta devuelven rutas inconsistentes. Pruebe en el IDE de GraphQL antes de integrarlo en el enrutamiento.
• Las páginas de opciones de ACF sin el argumento language recurren al idioma predeterminado. Pase siempre language para las consultas de la página de opciones en sitios multilingües.

Si se encuentra con un problema de integración que no aparece aquí, el equipo de soporte de WPML cubre el lado de WPML del stack de WPGraphQL las 24 horas del día, los 7 días de la semana.