Come interrogare i contenuti multilingue con WPGraphQL: filtraggio della lingua e traduzioni

Prima di iniziare

Installa e attiva questi plugin:

• WPGraphQL (il plugin open-source del progetto WPGraphQL).
• WPML e WPML Traduzione stringhe.
• WPML GraphQL (il componente aggiuntivo trattato in questa pagina).

Se usi anche Advanced Custom Fields:

• Advanced Custom Fields Multilingual (ACFML).
• WPGraphQL for Advanced Custom Fields (dal progetto WPGraphQL).

I tuoi contenuti di origine devono essere tradotti in WPML prima che le query sottostanti possano restituire qualcosa. Con Traduci tutto automaticamente attivato (l’impostazione predefinita di WPML 5), le traduzioni vengono prodotte in background man mano che pubblichi i contenuti. Per una configurazione manuale, invia i contenuti per la traduzione da WPML → Traduzioni → Bacheca. Gli articoli e i termini tradotti sono ciò che le query GraphQL sottostanti filtrano e restituiscono.

L’IDE GraphQL: dove testare le query

WPGraphQL aggiunge una schermata GraphQL → GraphQL IDE all’area di amministrazione di WordPress. Il Query Composer dell’IDE elenca tutti i campi disponibili, inclusi l’argomento language e il campo translations di WPML, ed esegue le query sul tuo sito live. Testa le query lì prima di collegarle al tuo framework front-end.

L’endpoint GraphQL per ogni lingua

WPGraphQL risponde all’indirizzo /graphql. Una query senza un argomento language restituisce i contenuti nella tua lingua predefinita. Per ottenere i contenuti in un’altra lingua, aggiungi where: { language: "es" } alla query.

Interrogare i contenuti per lingua

Aggiungi where: { language: "<code>" } a qualsiasi query di elenco: articoli, tipi di post personalizzati, termini della tassonomia, menu, voci di menu, commenti. Il codice della lingua è lo stesso che WPML usa ovunque (en, es, fr, pt-pt e così via). Passa language: "all" per restituire contemporaneamente i contenuti di tutte le lingue.

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

Quando un nodo di primo livello viene filtrato per lingua, gli elementi collegati (categorie, tag, tassonomie personalizzate) seguono automaticamente la stessa lingua. La query qui sopra restituisce gli articoli in spagnolo con le categorie in spagnolo, senza bisogno di argomenti aggiuntivi.

Recuperare ogni traduzione di un nodo in una sola query

Aggiungi il campo translations a qualsiasi query di articoli o tassonomie per restituire le versioni in altre lingue del nodo nello stesso payload:

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

Ogni articolo viene restituito con i suoi campi in inglese, più un array dei suoi slug e URI nelle altre lingue. Questa è la struttura utilizzata da un selettore di lingua renderizzato accanto al contenuto della pagina: una sola richiesta, tutte le alternative a cui il visitatore può passare.

Interrogare un articolo specifico per ID o slug in qualsiasi lingua

Per recuperare direttamente un singolo articolo tradotto (tramite il suo slug tradotto o l’ID del database), usa la query singolare 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 }
  }
}

Entrambe le query restituiscono l’articolo tradotto (titolo, slug, URI) senza ulteriori filtri sul front-end.

Menu multilingue

Interroga i menu e le voci di menu per lingua con lo stesso argomento where: { language }. Per ottenere le voci di una posizione del menu del tema, aggiungi anche la posizione:

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

Per elencare i menu di una lingua, usa la query menus:

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

label e url di ogni voce di menu vengono restituiti nella lingua interrogata. Le voci di menu che collegano ad articoli tradotti si risolvono automaticamente nell’URI tradotto. La query singolare menu non ha l’argomento language, quindi usa menus o menuItems per scegliere la lingua.

Lingue installate: per un selettore di lingua

Per un selettore di lingua globale (indipendente da un singolo articolo), usa le query languages e defaultLanguage per elencare tutte le lingue del sito:

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

Restituisce un nodo per ogni lingua attiva con l’URL della bandiera, il nome nativo, il nome tradotto e l’URL della home della lingua. Questi dati sono sufficienti per renderizzare un selettore con bandiera ed etichetta senza dover codificare manualmente l’elenco delle lingue.

Interrogare i campi personalizzati ACF per lingua

Quando ACFML e WPGraphQL for ACF sono attivi, i campi ACF su un articolo o un tipo di post personalizzato restituiscono i valori salvati su quell’articolo. Ogni traduzione ha i propri valori, quindi interroga l’articolo nella lingua di cui hai bisogno. Non sono necessari argomenti aggiuntivi.

Per le pagine delle opzioni ACF, che non sono collegate a un singolo articolo, aggiungi l’argomento language alla query della pagina delle opzioni:

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

L’argomento si aspetta un codice lingua che corrisponda a una delle lingue attive del tuo sito.

A partire da WPGraphQL for ACF 3.0.0, una pagina delle opzioni è presente nello schema GraphQL solo quando attivi show_in_graphql per essa. Senza questa impostazione, la query della pagina delle opzioni e il suo argomento language non esistono. Se registri la pagina delle opzioni nel codice, aggiungi l’impostazione lì:

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

Dettagli dell’autore tradotti

WPML GraphQL restituisce firstName, lastName, nickname e description tradotti degli utenti. Per tradurli:

1. Vai alla pagina WPML → Traduzione stringhe.
2. Nell’opzione Traduci le proprietà dell’utente, seleziona i ruoli utente e salva.
3. Traduci le stringhe nel dominio Authors.

Limitazioni note e soluzioni alternative

• URI tradotti in alcune strutture di query. Quando recuperi un articolo tradotto tramite URI (contentNode(id: "/de/some-slug/", idType: URI)), verifica che l’URI restituito corrisponda a quello pubblicato in quella lingua: alcune strutture di query restituiscono percorsi incoerenti. Fai un test nell’IDE GraphQL prima di collegarlo al routing.
• Le pagine delle opzioni ACF senza l’argomento language ricorrono alla lingua predefinita. Passa sempre language per le query delle pagine delle opzioni sui siti multilingue.

Se riscontri un problema di integrazione non elencato qui, il team di supporto di WPML copre il lato WPML dello stack WPGraphQL 24 ore su 24, 7 giorni su 7.