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 siguientes consultas puedan devolver algún resultado. Con la opción Traducir todo automáticamente activada (la predeterminada 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 siguientes consultas de GraphQL 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 activo. Pruebe allí las consultas antes de integrarlas en su framework de front-end.

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 carga útil:

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 una matriz de sus slugs y URI en otros idiomas. Esa 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 directamente una sola entrada traducida (por su slug traducido o por el ID de la 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 filtrado adicional en el front-end.

Menús multilingües

Consulte los menús y los elementos del menú por idioma con el mismo argumento language:

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

El label y la 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 en el URI traducido. Esta compatibilidad se añadió en WPML GraphQL 1.1.0.

Idiomas instalados: para un selector de idiomas

Para un selector de idiomas global (independiente de cualquier entrada individual), utilice las consultas languages y defaultLanguage para enumerar 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 datos son suficientes para mostrar un selector de idiomas con bandera y etiqueta sin tener que codificar la lista de idiomas de forma manual.

Consultar campos personalizados de ACF por idioma

Cuando ACFML y WPGraphQL for ACF están activos, los campos de ACF en entradas y tipos de contenido personalizado siguen automáticamente el idioma de la entrada anfitriona. No se necesita ningún argumento adicional. 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.

Limitaciones conocidas y soluciones alternativas

• Los metadatos de usuario y de autor no devuelven valores traducidos. Si muestra las biografías de los autores por idioma, guarde la biografía traducida en un campo de ACF en el usuario y consulte ese campo en su lugar.
• URI traducidos en algunas estructuras de consulta. Al obtener una entrada traducida por URI (contentNode(id: "/de/some-slug/", idType: URI)), compruebe que el URI devuelto coincide con lo que está publicado en el idioma, ya que algunas estructuras de consulta devuelven rutas incoherentes. Pruébelo 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 en 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 atiende la parte de WPML del stack de WPGraphQL las 24 horas del día, los 7 días de la semana.