New translations best-practices.mdx (Portuguese)

Author: benface

website/src/pages/pt/subgraphs/querying/best-practices.mdx

@@ -52,31 +52,31 @@ query [operationName]([variableName]: [variableType]) {
 
 ## Regras para Escrever Queries em GraphQL
 
-- Each `queryName` must only be used once per operation.
-- Each `field` must be used only once in a selection (we cannot query `id` twice under `token`)
-- Some `field`s or queries (like `tokens`) return complex types that require a selection of sub-field. Not providing a selection when expected (or providing one when not expected - for example, on `id`) will raise an error. To know a field type, please refer to [Graph Explorer](/subgraphs/explorer/).
+- Cada `queryName` só pode ser usado uma vez por operação.
+- Cada `field` deve ser usado apenas uma vez numa seleção (não podemos solicitar a `id` duas vezes sob o `token`)
+- Alguns `field`s ou queries (como `tokens`) retornam tipos complexos que exigem uma seleção de sub-campo. Caso uma seleção não seja fornecida quando esperada (ou fornecida quando não é esperada — por exemplo, em `id`), aparecerá um erro. Para conhecer um tipo de campo, consulte o [Graph Explorer](/subgraphs/explorer/).
 - Qualquer variável apontada a um argumento deve corresponder ao seu tipo.
 - Em uma lista dada de variáveis, cada uma delas deve ser única.
 - Todas as variáveis definidas devem ser usadas.
 
-> Note: Failing to follow these rules will result in an error from The Graph API.
+> Não seguir as regras acima causará um erro da API do The Graph.
 
-For a complete list of rules with code examples, check out [GraphQL Validations guide](/resources/release-notes/graphql-validations-migration-guide/).
+Para uma lista completa de regras com exemplos de código, veja o [guia de Validações da GraphQL](/resources/release-notes/graphql-validations-migration-guide/).
 
 ### Como enviar um query a uma API GraphQL
 
-GraphQL is a language and set of conventions that transport over HTTP.
+GraphQL é uma linguagem e um conjunto de convenções transportadas através do HTTP.
 
-It means that you can query a GraphQL API using standard `fetch` (natively or via `@whatwg-node/fetch` or `isomorphic-fetch`).
+Ou seja, dá para fazer um query numa API GraphQL com o `fetch` normal (nativamente ou via `@whatwg-node/fetch` ou `isomorphic-fetch`).
 
-However, as mentioned in ["Querying from an Application"](/subgraphs/querying/from-an-application/), it's recommended to use `graph-client`, which supports the following unique features:
+Porém, conforme mencionado em ["Como Fazer Queries de Um Aplicativo"](/subgraphs/querying/from-an-application/), recomendamos usar o `graph-client`, que apoia as seguintes funções únicas:
 
 - Gestão de Subgraph Cross-chain: Queries de múltiplos subgraphs numa única consulta
-- [Automatic Block Tracking](https://github.com/graphprotocol/graph-client/blob/main/packages/block-tracking/README.md)
-- [Automatic Pagination](https://github.com/graphprotocol/graph-client/blob/main/packages/auto-pagination/README.md)
+- [Rastreamento Automático de Blocos](https://github.com/graphprotocol/graph-client/blob/main/packages/block-tracking/README.md)
+- [Paginação Automática](https://github.com/graphprotocol/graph-client/blob/main/packages/auto-pagination/README.md)
 - Resultado totalmente digitado
 
-Here's how to query The Graph with `graph-client`:
+Aqui está como fazer queries para o The Graph com o `graph-client`:
 
 ```tsx
 import { execute } from '../.graphclient'
@@ -100,15 +100,15 @@ async function main() {
 main()
 ```
 
-More GraphQL client alternatives are covered in ["Querying from an Application"](/subgraphs/querying/from-an-application/).
+Para mais alternativas de clientes para GraphQL, veja ["Como Fazer Queries de Um Aplicativo"](/subgraphs/querying/from-an-application/).
 
 ---
 
 ## Boas práticas
 
 ### Sempre escreva consultas estáticas
 
-A common (bad) practice is to dynamically build query strings as follows:
+É (um erro) comum construir strings de query dinamicamente, como no exemplo a seguir:
 
 ```tsx
 const id = params.id
@@ -124,14 +124,14 @@ query GetToken {
 // Execute query...
 ```
 
-While the above snippet produces a valid GraphQL query, **it has many drawbacks**:
+Enquanto o trecho acima produz um query válido na GraphQL, **isto traz muitas desvantagens**:
 
-- it makes it **harder to understand** the query as a whole
-- developers are **responsible for safely sanitizing the string interpolation**
-- not sending the values of the variables as part of the request parameters **prevent possible caching on server-side**
-- it **prevents tools from statically analyzing the query** (ex: Linter, or type generations tools)
+- deixa o query **mais difícil de entender**
+- os programadores são **responsáveis por higienizar a interpolação de string com segurança**
+- não enviar os valores das variáveis como parte dos parâmetros de pedido **impede um possível caching no lado do servidor**
+- isto **impede as ferramentas de analisar o query estaticamente** (por ex. Linter ou ferramentas de geração de tipos)
 
-For this reason, it is recommended to always write queries as static strings:
+Por isto, é recomendado sempre escrever queries como strings estáticas:
 
 ```tsx
 import { execute } from 'your-favorite-graphql-client'
@@ -153,18 +153,18 @@ const result = await execute(query, {
 })
 ```
 
-Doing so brings **many advantages**:
+Isto traz **muitas vantagens**:
 
-- **Easy to read and maintain** queries
-- The GraphQL **server handles variables sanitization**
-- **Variables can be cached** at server-level
-- **Queries can be statically analyzed by tools** (more on this in the following sections)
+- Queries **fáceis de ler e manter**
+- O servidor GraphQL **cuida da higienização de variáveis**
+- **Variáveis podem ser guardadas em cache** no nível do servidor
+- **Queries podem ser analisados estaticamente por ferramentas** (mais sobre isto nas secções seguintes)
 
-### How to include fields conditionally in static queries
+### Como incluir campos condicionalmente em queries estáticos
 
-You might want to include the `owner` field only on a particular condition.
+Talvez queira incluir o campo `owner` apenas com uma condição particular.
 
-For this, you can leverage the `@include(if:...)` directive as follows:
+Para isto, use a diretiva `@include(if:...)` a seguir:
 
 ```tsx
 import { execute } from 'your-favorite-graphql-client'
@@ -187,18 +187,18 @@ const result = await execute(query, {
 })
 ```
 
-> Note: The opposite directive is `@skip(if: ...)`.
+> Observação: a diretiva oposta é `@skip(if: ...)`.
 
 ### Pergunte pelo que queres
 
-GraphQL became famous for its "Ask for what you want" tagline.
+A GraphQL ficou famosa por sua frase de efeito "pergunte pelo que queres".
 
-For this reason, there is no way, in GraphQL, to get all available fields without having to list them individually.
+Por isto, no GraphQL, não há como obter todos os campos disponíveis sem ter que listá-los individualmente.
 
 - Ao consultar APIs GraphQL, sempre considere fazer query apenas dos campos que serão usados.
-- Make sure queries only fetch as many entities as you actually need. By default, queries will fetch 100 entities in a collection, which is usually much more than what will actually be used, e.g., for display to the user. This applies not just to top-level collections in a query, but even more so to nested collections of entities.
+- Tenha certeza que os queries só retornarão o máximo necessário de entidades. Por natureza, os queries retirarão 100 entidades em uma coleção, muito mais do que realmente será usado; por ex., para fins de amostra ao usuário. Isto serve não só para coleções de alto nível em um query, mas também — especialmente — para coleções aninhadas de entidades.
 
-For example, in the following query:
+Por exemplo, no query seguinte:
 
 ```graphql
 query listTokens {
@@ -213,15 +213,15 @@ query listTokens {
 }
 ```
 
-The response could contain 100 transactions for each of the 100 tokens.
+A resposta pode conter 100 transações para cada um dos 100 tokens.
 
-If the application only needs 10 transactions, the query should explicitly set `first: 10` on the transactions field.
+Se o aplicativo só precisa de 10 transações, o query deve configurar explicitamente `first: 10` no campo de transações.
 
 ### Use uma única query para pedir vários registros
 
-By default, subgraphs have a singular entity for one record. For multiple records, use the plural entities and filter: `where: {id_in:[X,Y,Z]}` or `where: {volume_gt:100000}`
+Por padrão, subgraphs têm uma entidade singular para um registro. Para múltiplos registros, use as entidades plurais e o filtro: `where: {id_in:[X,Y,Z]}` ou `where: {volume_gt:100000}`
 
-Example of inefficient querying:
+Um exemplo de query ineficaz:
 
 ```graphql
 query SingleRecord {
@@ -238,7 +238,7 @@ query SingleRecord {
 }
 ```
 
-Example of optimized querying:
+Um exemplo de query otimizado:
 
 ```graphql
 query ManyRecords {
@@ -251,7 +251,7 @@ query ManyRecords {
 
 ### Combine múltiplas queries em um único pedido
 
-Your application might require querying multiple types of data as follows:
+O seu aplicativo pode exigir queries de múltiplos tipos de dados, como a seguir:
 
 ```graphql
 import { execute } from "your-favorite-graphql-client"
@@ -281,9 +281,9 @@ const [tokens, counters] = Promise.all(
 )
 ```
 
-While this implementation is totally valid, it will require two round trips with the GraphQL API.
+Enquanto esta implementação é totalmente válida, ela exigirá duas rondas totais com a API da GraphQL.
 
-Fortunately, it is also valid to send multiple queries in the same GraphQL request as follows:
+Felizmente, também vale enviar múltiplos queries no mesmo pedido à GraphQL, como a seguir:
 
 ```graphql
 import { execute } from "your-favorite-graphql-client"
@@ -304,13 +304,13 @@ query GetTokensandCounters {
 const  { result: { tokens, counters } } = execute(query)
 ```
 
-This approach will **improve the overall performance** by reducing the time spent on the network (saves you a round trip to the API) and will provide a **more concise implementation**.
+Este método **melhorará o desempenho em geral** ao reduzir o tempo gasto na rede (porque poupa uma viagem ao redor da API) e fornecerá **implementações mais concisas**.
 
 ### Como Aproveitar Fragmentos GraphQL
 
-A helpful feature to write GraphQL queries is GraphQL Fragment.
+O GraphQL Fragment é uma ferramenta útil para a escrita de queries em GraphQL.
 
-Looking at the following query, you will notice that some fields are repeated across multiple Selection-Sets (`{ ... }`):
+No seguinte query, perceba que alguns campos são repetidos em vários Selection-Sets (`{ ... }`):
 
 ```graphql
 query {
@@ -330,12 +330,12 @@ query {
 }
 ```
 
-Such repeated fields (`id`, `active`, `status`) bring many issues:
+Estes campos repetidos (`id`, `active`, `status`) trazem muitos problemas:
 
-- More extensive queries become harder to read.
-- When using tools that generate TypeScript types based on queries (_more on that in the last section_), `newDelegate` and `oldDelegate` will result in two distinct inline interfaces.
+- Queries mais extensos ficam difíceis de ler.
+- Ao usar ferramentas que geram tipos TypeScript baseados em queries (_mais na última secção_), `newDelegate` e `oldDelegate` retornarão duas interfaces distintas em inline.
 
-A refactored version of the query would be the following:
+Fatorizado novamente, o query ficaria assim:
 
 ```graphql
 query {
@@ -359,27 +359,27 @@ fragment DelegateItem on Transcoder {
 }
 ```
 
-Using GraphQL `fragment` will improve readability (especially at scale) and result in better TypeScript types generation.
+Usar o `fragment` ("fragmento") da GraphQL melhorará a legibilidade (especialmente em escala) e também melhorará a geração de tipos TypeScript.
 
-When using the types generation tool, the above query will generate a proper `DelegateItemFragment` type (_see last "Tools" section_).
+Ao usar a ferramenta de geração de tipos, o query acima gerará um tipo `DelegateItemFragment` apropriado (_veja a última secção "Ferramentas"_).
 
 ### O que fazer e o que não fazer em Fragments GraphQL
 
 ### A base do fragment deve ser um tipo
 
-A Fragment cannot be based on a non-applicable type, in short, **on type not having fields**:
+Um Fragment não pode ser baseado num tipo não aplicável; ou seja, **um tipo sem campos**:
 
 ```graphql
 fragment MyFragment on BigInt {
   # ...
 }
 ```
 
-`BigInt` is a **scalar** (native "plain" type) that cannot be used as a fragment's base.
+O `BigInt` é um **escalar** (tipo "plano" nativo) que não pode ser usado como a base de um fragmento.
 
 #### Como espalhar um Fragment
 
-Fragments are defined on specific types and should be used accordingly in queries.
+Fragmentos são definidos em tipos específicos e devem ser usados de acordo nos queries.
 
 Exemplo:
 
@@ -402,20 +402,20 @@ fragment VoteItem on Vote {
 }
 ```
 
-`newDelegate` and `oldDelegate` are of type `Transcoder`.
+`newDelegate` e `oldDelegate` são do tipo `Transcoder`.
 
-It is not possible to spread a fragment of type `Vote` here.
+Não é possível espalhar um fragmento do tipo `Vote` aqui.
 
 #### Defina o Fragment como uma unidade de negócios atômica de dados
 
-GraphQL `Fragment`s must be defined based on their usage.
+`Fragment`s da GraphQL devem ser definidos com base no seu uso.
 
-For most use-case, defining one fragment per type (in the case of repeated fields usage or type generation) is sufficient.
+Para a maioria dos casos de uso, definir um fragmento por tipo (no caso do uso repetido de campos ou geração de tipos) já é o suficiente.
 
-Here is a rule of thumb for using fragments:
+Aqui estão algumas regras básicas para o uso de Fragmentos:
 
-- When fields of the same type are repeated in a query, group them in a `Fragment`.
-- When similar but different fields are repeated, create multiple fragments, for instance:
+- Quando campos do mesmo tipo se repetem em um query, agrupe-os em um `Fragment`.
+- Quando campos parecidos (mas não idênticos) se repetem, crie múltiplos fragmentos, por exemplo:
 
 ```graphql
 # base fragment (mostly used in listing)
@@ -438,51 +438,51 @@ fragment VoteWithPoll on Vote {
 
 ---
 
-## The Essential Tools
+## Ferramentas Essenciais
 
 ### Exploradores do GraphQL baseados em web
 
-Iterating over queries by running them in your application can be cumbersome. For this reason, don't hesitate to use [Graph Explorer](https://thegraph.com/explorer) to test your queries before adding them to your application. Graph Explorer will provide you a preconfigured GraphQL playground to test your queries.
+Pode ser até chato executar queries no seu aplicativo para iterar sobre elas. Por isto, não hesite em usar o [Graph Explorer](https://thegraph.com/explorer) para testar os seus queries antes de adicioná-los. O Graph Explorer fornecerá um ambiente de testes GraphQL pré-configurado para testar os seus queries.
 
-If you are looking for a more flexible way to debug/test your queries, other similar web-based tools are available such as [Altair](https://altairgraphql.dev/) and [GraphiQL](https://graphiql-online.com/graphiql).
+Se procura uma maneira mais flexível de depurar/testar seus queries, há outras ferramentas semelhantes baseadas na web, como [Altair](https://altairgraphql.dev/) e [GraphiQL](https://graphiql-online.com/graphiql).
 
 ### GraphQL Linting
 
-In order to keep up with the mentioned above best practices and syntactic rules, it is highly recommended to use the following workflow and IDE tools.
+Para acompanhar as melhores práticas e regras sintáticas explicadas acima, vale muito a pena utilizar as ferramentas IDE e de fluxo de trabalho a seguir.
 
-**GraphQL ESLint**
+**ESLint — GraphQL**
 
-[GraphQL ESLint](https://the-guild.dev/graphql/eslint/docs/getting-started) will help you stay on top of GraphQL best practices with zero effort.
+O [ESLint da GraphQL](https://the-guild.dev/graphql/eslint/docs/getting-started) te ajudará a acompanhar as melhores práticas da GraphQL sem sofrimento.
 
-[Setup the "operations-recommended"](https://the-guild.dev/graphql/eslint/docs/configs) config will enforce essential rules such as:
+[Organize a configuração "operations-recommended"](https://the-guild.dev/graphql/eslint/docs/configs) para executar regras essenciais como:
 
-- `@graphql-eslint/fields-on-correct-type`: is a field used on a proper type?
-- `@graphql-eslint/no-unused variables`: should a given variable stay unused?
+- `@graphql-eslint/fields-on-correct-type`: um campo está num tipo apropriado?
+- `@graphql-eslint/no-unused variables`: uma variável usada deve ficar sem uso?
 - e mais!
 
-This will allow you to **catch errors without even testing queries** on the playground or running them in production!
+Isto permitirá-lhe **detetar erros mesmo sem testar queries** no playground ou mesmo executá-los na produção!
 
 ### Plugins IDE
 
-**VSCode and GraphQL**
+**VSCode e GraphQL**
 
-The [GraphQL VSCode extension](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql) is an excellent addition to your development workflow to get:
+A [extensão VSCode da GraphQL](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql) é uma adição excelente ao seu fluxo de programação que permite:
 
-- Syntax highlighting
-- Autocomplete suggestions
-- Validation against schema
-- Snippets
-- Go to definition for fragments and input types
+- Destaque de sintaxe
+- Sugestões de preenchimento automático
+- Validação perante schema
+- Snippets (blocos de código reutilizáveis)
+- Definições de fragmentos e tipos de entrada
 
-If you are using `graphql-eslint`, the [ESLint VSCode extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) is a must-have to visualize errors and warnings inlined in your code correctly.
+Se utilizar o `graphql-eslint`, a [extensão VSCode para o ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) é essencial para visualizar corretamente erros e avisos embutidos no seu código.
 
-**WebStorm/Intellij and GraphQL**
+**WebStorm/Intellij e GraphQL**
 
-The [JS GraphQL plugin](https://plugins.jetbrains.com/plugin/8097-graphql/) will significantly improve your experience while working with GraphQL by providing:
+O [plugin JavaScript para a GraphQL](https://plugins.jetbrains.com/plugin/8097-graphql/) melhorará muito a sua experiência com a GraphQL com:
 
-- Syntax highlighting
-- Autocomplete suggestions
-- Validation against schema
-- Snippets
+- Destaque de sintaxe
+- Sugestões de preenchimento automático
+- Validação perante schema
+- Snippets (blocos de código reutilizáveis)
 
-For more information on this topic, check out the [WebStorm article](https://blog.jetbrains.com/webstorm/2019/04/featured-plugin-js-graphql/) which showcases all the plugin's main features.
+Para mais informações sobre este tópico, veja o [artigo do WebStorm](https://blog.jetbrains.com/webstorm/2019/04/featured-plugin-js-graphql/), que demonstra todas as funções principais do plugin.