Como consultar conteúdo multilíngue com o WPGraphQL – filtragem de idiomas e traduções

Antes de começar

Instale e ative estes plugins:

• WPGraphQL (o plugin de código aberto do projeto WPGraphQL).
• WPML e WPML Tradução de Strings.
• WPML GraphQL (o complemento que esta página aborda).

Se você também usa o Advanced Custom Fields:

• Advanced Custom Fields Multilingual (ACFML).
• WPGraphQL for Advanced Custom Fields (do projeto WPGraphQL).

Seu conteúdo de origem precisa ser traduzido no WPML antes que as consultas abaixo tenham algo a retornar. Com o Traduzir tudo automaticamente ativado (o padrão do WPML 5), as traduções são produzidas em segundo plano à medida que você publica o conteúdo. Para uma configuração manual, envie o conteúdo para tradução em WPML > Traduções > Painel. Os posts e termos traduzidos são o que as consultas GraphQL abaixo filtram e retornam.

O GraphQL IDE – onde testar as consultas

O WPGraphQL adiciona uma tela GraphQL > GraphQL IDE ao painel de administração do WordPress. O Query Composer do IDE lista todos os campos disponíveis, incluindo o argumento language e o campo translations do WPML, e executa consultas no seu site de produção. Teste as consultas lá antes de integrá-las ao seu framework de front-end.

Consultar conteúdo por idioma

Adicione where: { language: "<code>" } a qualquer consulta de lista: posts, tipos de post personalizados, termos de taxonomia, menus, itens de menu, comentários. O código do idioma é o mesmo código que o WPML usa em todos os lugares (en, es, fr, pt-pt e assim por diante). Passe language: "all" para retornar o conteúdo de todos os idiomas de uma só vez.

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

Quando um nó de nível superior é filtrado por idioma, os itens conectados (categorias, tags, taxonomias personalizadas) seguem automaticamente o mesmo idioma. A consulta acima retorna posts em espanhol com categorias em espanhol, sem a necessidade de argumentos extras.

Buscar todas as traduções de um nó em uma única consulta

Adicione o campo translations a qualquer consulta de post ou taxonomia para retornar as versões em outros idiomas do nó no mesmo payload:

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

Cada post retorna com seus campos em inglês, mais um array de seus slugs e URIs em outros idiomas. Esse é o formato que um seletor de idiomas renderizado ao lado do conteúdo da página usa: uma requisição, todas as alternativas para as quais o visitante pode alternar.

Consultar um post específico por ID ou slug em qualquer idioma

Para buscar um único post traduzido diretamente (pelo seu slug traduzido ou pelo ID do banco de dados), use a consulta singular post com 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 as consultas retornam o post traduzido (título, slug, URI) sem filtragem adicional no front-end.

Menus multilíngues

Consulte menus e itens de menu por idioma com o mesmo argumento language:

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

O label e o url de cada item de menu retornam no idioma consultado. Os itens de menu que apontam para posts traduzidos resolvem para o URI traduzido automaticamente. Esse suporte foi adicionado no WPML GraphQL 1.1.0.

Idiomas instalados – para um seletor de idiomas

Para um seletor de idiomas global (independente de qualquer post individual), use as consultas languages e defaultLanguage para listar todos os idiomas do site:

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

Retorna um nó por idioma ativo com o URL da bandeira, nome nativo, nome traduzido e o URL da página inicial do idioma. Isso fornece dados suficientes para renderizar um seletor com bandeira e rótulo sem fixar a lista de idiomas no código.

Consultar campos personalizados do ACF por idioma

Quando o ACFML e o WPGraphQL for ACF estão ativos, os campos do ACF em posts e tipos de post personalizados seguem automaticamente o idioma do post hospedeiro. Nenhum argumento extra é necessário. Para as ACF Options Pages, que não estão vinculadas a um único post, adicione o argumento language à consulta da Options Page:

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

O argumento espera um código de idioma que corresponda a um dos idiomas ativos do seu site.

Limitações conhecidas e soluções alternativas

• Os metadados de autor e usuário não retornam valores traduzidos. Se você exibir biografias de autores por idioma, armazene a biografia traduzida em um campo do ACF no usuário e consulte esse campo em vez disso.
• URIs traduzidos em alguns formatos de consulta. Ao buscar um post traduzido por URI (contentNode(id: "/de/some-slug/", idType: URI)), verifique se o URI retornado corresponde ao que está publicado no idioma – alguns formatos de consulta retornam caminhos inconsistentes. Teste no GraphQL IDE antes de integrar ao roteamento.
• As ACF Options Pages sem o argumento language revertem para o idioma padrão. Sempre passe language para consultas de Options Page em sites multilíngues.

Se você encontrar um problema de integração não listado aqui, a equipe de suporte do WPML cobre o lado do WPML da stack do WPGraphQL 24/7.