Come interrogare i contenuti multilingue con WPGraphQL – Filtro per 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 l’opzione Traduci tutto automaticamente attiva (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, tra cui l’argomento language e il campo translations di WPML, ed esegue le query sul tuo sito di produzione. Testa le query lì prima di integrarle nel tuo framework front-end.

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 codice che WPML utilizza 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 precedente restituisce gli articoli in spagnolo con le categorie in spagnolo, senza bisogno di argomenti aggiuntivi.

Recuperare tutte le traduzioni di un nodo in una sola query

Aggiungi il campo translations a qualsiasi query di articolo o tassonomia 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 visualizzato accanto al contenuto della pagina: una sola richiesta, tutte le alternative a cui il visitatore può passare.

Interrogare un articolo specifico tramite 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 language:

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

Il label e l’url di ogni voce di menu vengono restituiti nella lingua interrogata. Le voci di menu che rimandano ad articoli tradotti si risolvono automaticamente nell’URI tradotto. Questo supporto è stato aggiunto in WPML GraphQL 1.1.0.

Lingue installate: per un selettore di lingua

Per un selettore di lingua globale (indipendente da qualsiasi 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 page della lingua. Questi dati sono sufficienti per visualizzare un selettore con bandiera ed etichetta senza inserire l’elenco delle lingue direttamente nel codice.

Interrogare i campi personalizzati di ACF per lingua

Quando ACFML e WPGraphQL for ACF sono attivi, i campi ACF sugli articoli e sui tipi di post personalizzati seguono automaticamente la lingua dell’articolo ospitante. Non è necessario alcun argomento aggiuntivo. Per le Pagine opzioni di 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 prevede un codice lingua che corrisponde a una delle lingue attive del tuo sito.

Limitazioni note e soluzioni alternative

• I metadati dell’autore e dell’utente non restituiscono valori tradotti. Se visualizzi le biografie degli autori per lingua, memorizza la biografia tradotta in un campo ACF sull’utente e interroga invece quel campo.
• 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 nella lingua: alcune strutture di query restituiscono percorsi incoerenti. Fai un test nell’IDE GraphQL prima di integrare il tutto nel routing.
• Le Pagine opzioni di ACF senza l’argomento language ripiegano sulla 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/7.