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 IDE do GraphQL – 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 em seu site de produção. Teste as consultas lá antes de integrá-las ao seu framework de front-end.

O endpoint do GraphQL para cada idioma

O WPGraphQL responde em /graphql. Uma consulta sem um argumento language retorna o conteúdo no seu idioma padrão. Para obter o conteúdo em outro idioma, adicione where: { language: "es" } à consulta.

Consulte o 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 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.

Busque 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, além de 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 solicitação, todas as alternativas para as quais o visitante pode alternar.

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

Para buscar diretamente um único post traduzido (por seu slug traduzido ou por ID do banco de dados), use a consulta post singular 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 where: { language }. Para obter os itens de um local de menu do tema, adicione também o local:

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

Para listar os menus de um idioma, use a consulta menus:

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

O label e o url de cada item de menu retornam no idioma consultado. Os itens de menu que apontam para posts traduzidos são resolvidos automaticamente para o URI traduzido. A consulta menu singular não tem o argumento language, portanto, use menus ou menuItems para escolher o idioma.

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 a URL da bandeira, nome nativo, nome traduzido e a URL inicial do idioma. Isso é dado suficiente para renderizar um seletor de bandeira e rótulo sem fixar a lista de idiomas no código.

Consulte campos personalizados do ACF por idioma

Quando o ACFML e o WPGraphQL for ACF estão ativos, os campos do ACF em um post ou tipo de post personalizado retornam os valores salvos nesse post. Cada tradução tem seus próprios valores, portanto, consulte o post no idioma que você precisa. Nenhum argumento extra é necessário.

Para as páginas de opções do ACF, que não estão vinculadas a um único post, adicione o argumento language à consulta da página de opções:

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.

Desde o WPGraphQL for ACF 3.0.0, uma página de opções está no esquema do GraphQL apenas quando você ativa o show_in_graphql para ela. Sem isso, a consulta da página de opções e seu argumento language não existem. Se você registrar a página de opções no código, adicione a configuração lá:

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

Detalhes do autor traduzidos

O WPML GraphQL retorna os campos firstName, lastName, nickname e description traduzidos dos usuários. Para traduzi-los:

1. Vá para a página WPML → Tradução de Strings.
2. Na opção Traduzir propriedades do usuário, selecione as funções de usuário e salve.
3. Traduza as strings no domínio Authors.

Limitações conhecidas e soluções alternativas

• 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 IDE do GraphQL antes de integrar ao roteamento.
• Páginas de opções do ACF sem o argumento language recorrem ao idioma padrão. Sempre passe language para consultas de página de opções 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 WPML da stack do WPGraphQL 24 horas por dia, 7 dias por semana.