docs(i18n): guide (pt-br)

Author: vishr

site/src/content/docs/pt-br/guide/binding.md

@@ -0,0 +1,151 @@
+---
+title: Binding
+description: Analise dados de request em structs Go tipadas a partir de path, query, header e body.
+sidebar:
+  order: 5
+---
+
+Analisar dados de request é uma parte crucial de uma aplicação web. No Echo isso se chama
+_binding_, e ele pode ler de quatro partes de um request HTTP:
+
+- Parâmetros de caminho da URL
+- Parâmetros de query da URL
+- Headers
+- Body do request
+
+## Binding com tags de struct
+
+Defina uma struct com tags que especificam a fonte e a chave dos dados, então chame `c.Bind()`
+com um ponteiro para ela. Aqui o parâmetro de query `id` faz binding para o campo `ID`:
+
+```go
+type User struct {
+	ID string `query:"id"`
+}
+
+// handler for /users?id=<userID>
+var user User
+if err := c.Bind(&user); err != nil {
+	return c.String(http.StatusBadRequest, "bad request")
+}
+```
+
+### Fontes de dados
+
+| Tag      | Fonte |
+| -------- | ----- |
+| `query`  | Parâmetro de query |
+| `param`  | Parâmetro de caminho |
+| `header` | Valor de header |
+| `form`   | Dados de formulário (query + body) |
+| `json`   | Body do request (`encoding/json`) |
+| `xml`    | Body do request (`encoding/xml`) |
+
+Campos de path, query, header e form exigem uma **tag explícita**. JSON e XML usam
+o nome do campo da struct quando a tag é omitida, igual à biblioteca padrão.
+
+### Tipos de conteúdo do body
+
+Ao decodificar o body do request, o header `Content-Type` seleciona o decoder:
+
+- `application/json`
+- `application/xml`
+- `application/x-www-form-urlencoded`
+
+### Múltiplas fontes e precedência
+
+Um campo pode declarar várias fontes. Os dados fazem binding nesta ordem, cada etapa
+sobrescrevendo a anterior:
+
+1. Parâmetros de caminho
+2. Parâmetros de query (somente GET / DELETE)
+3. Body do request
+
+```go
+type User struct {
+	ID string `param:"id" query:"id" form:"id" json:"id" xml:"id"`
+}
+```
+
+### Binding direto de uma fonte
+
+```go
+echo.BindBody(c, &payload)        // request body
+echo.BindQueryParams(c, &payload) // query parameters
+echo.BindPathValues(c, &payload)  // path parameters
+echo.BindHeaders(c, &payload)     // headers
+```
+
+:::note
+Headers **não** são incluídos por `c.Bind()`. Faça binding deles diretamente com `echo.BindHeaders`.
+:::
+
+:::caution[Segurança]
+Não faça binding diretamente em structs de negócio. Se uma struct vinculada expuser um campo `IsAdmin bool`,
+um body de request `{"IsAdmin": true}` o definiria. Use um DTO dedicado e faça o mapeamento
+explicitamente:
+:::
+
+```go
+type UserDTO struct {
+	Name  string `json:"name" form:"name" query:"name"`
+	Email string `json:"email" form:"email" query:"email"`
+}
+
+e.POST("/users", func(c *echo.Context) error {
+	var dto UserDTO
+	if err := c.Bind(&dto); err != nil {
+		return c.String(http.StatusBadRequest, "bad request")
+	}
+	user := User{Name: dto.Name, Email: dto.Email, IsAdmin: false}
+	executeSomeBusinessLogic(user)
+	return c.JSON(http.StatusOK, user)
+})
+```
+
+## Binding fluente
+
+Para binding explícito e type-safe de uma única fonte, use os binders fluentes. Eles
+encadeiam configuração e execução, coletando erros:
+
+```go
+// /api/search?active=true&id=1&id=2&id=3&length=25
+var opts struct {
+	IDs    []int64
+	Active bool
+}
+length := int64(50)
+
+err := echo.QueryParamsBinder(c).
+	Int64("length", &length).
+	Int64s("id", &opts.IDs).
+	Bool("active", &opts.Active).
+	BindError() // first error, if any
+```
+
+Binders disponíveis: `echo.QueryParamsBinder(c)`, `echo.PathValuesBinder(c)`,
+`echo.FormFieldBinder(c)`. Termine uma cadeia com `BindError()` (primeiro erro) ou
+`BindErrors()` (todos os erros). `FailFast(false)` executa a cadeia inteira; ele vem ativado por padrão.
+
+Cada tipo suportado oferece métodos `Type(...)`, `MustType(...)`, `Types(...)` (slices) e
+`MustTypes(...)` — por exemplo, `Int64`, `MustInt64`, `Int64s`. Use
+`BindWithDelimiter("id", &dest, ",")` para separar valores unidos por vírgula.
+
+## Binder customizado
+
+Registre um binder customizado via `Echo#Binder`:
+
+```go
+type CustomBinder struct{}
+
+func (cb *CustomBinder) Bind(c *echo.Context, i any) error {
+	db := new(echo.DefaultBinder)
+	if err := db.Bind(c, i); err != echo.ErrUnsupportedMediaType {
+		return err
+	}
+	// custom logic here
+	return nil
+}
+
+e.Binder = &CustomBinder{}
+```

site/src/content/docs/pt-br/guide/context.md

@@ -0,0 +1,78 @@
+---
+title: Context
+description: O objeto por request que carrega request, response, parâmetros e helpers.
+sidebar:
+  order: 4
+---
+
+`echo.Context` representa o contexto do request HTTP atual. Um ponteiro para ele
+(`*echo.Context`) é passado para todo handler e middleware, carregando o request e a
+response, parâmetros de caminho, dados vinculados e helpers para criar responses.
+
+```go
+func handler(c *echo.Context) error {
+	// ...
+	return nil
+}
+```
+
+## Ler entrada
+
+```go
+id := c.Param("id")            // path parameter
+q := c.QueryParam("q")         // query string value
+all := c.QueryParams()         // url.Values of all query params
+name := c.FormValue("name")    // form field (URL + body)
+ua := c.Request().Header.Get(echo.HeaderUserAgent)
+```
+
+Há helpers `*Or` correspondentes que retornam um padrão quando um valor está ausente —
+`c.ParamOr("id", "0")`, `c.QueryParamOr("page", "1")`, `c.FormValueOr(...)`.
+
+## Escrever responses
+
+```go
+c.String(http.StatusOK, "plain text")
+c.JSON(http.StatusOK, payload)
+c.JSONPretty(http.StatusOK, payload, "  ")
+c.HTML(http.StatusOK, "<b>hi</b>")
+c.XML(http.StatusOK, payload)
+c.Blob(http.StatusOK, "application/pdf", bytes)
+c.Stream(http.StatusOK, "application/octet-stream", reader)
+c.NoContent(http.StatusNoContent)
+c.Redirect(http.StatusFound, "/elsewhere")
+```
+
+## Arquivos
+
+```go
+c.File("public/report.pdf")             // serve a file
+c.Attachment("invoice.pdf", "inv.pdf")  // prompt download
+c.Inline("photo.png", "photo.png")      // render inline
+```
+
+## Armazenamento por request
+
+Compartilhe dados entre middleware e handlers com `Get`/`Set`:
+
+```go
+c.Set("user", u)
+u, _ := c.Get("user").(*User)
+```
+
+Acesso tipado está disponível por meio dos helpers de generics:
+
+```go
+u, err := echo.ContextGet[*User](c, "user")
+```
+
+## Binding e validação
+
+`c.Bind()` analisa dados do request em uma struct; veja [Binding](/pt-br/guide/binding/).
+
+```go
+var dto CreateUser
+if err := c.Bind(&dto); err != nil {
+	return echo.ErrBadRequest
+}
+```

site/src/content/docs/pt-br/guide/cookies.md

@@ -0,0 +1,72 @@
+---
+title: Cookies
+description: Crie, leia e liste HTTP cookies usando o tipo padrão http.Cookie.
+sidebar:
+  order: 11
+---
+
+Um cookie é um pequeno pedaço de dados que um servidor envia ao navegador, que o navegador
+armazena e envia de volta em requests subsequentes. Cookies permitem que sites lembrem
+informações com estado, como carrinho de compras, estado de autenticação ou valores de formulário
+inseridos anteriormente.
+
+Echo usa o tipo padrão `http.Cookie` do Go para adicionar e recuperar cookies do
+`echo.Context` em um handler.
+
+## Atributos de cookie
+
+| Atributo   | Opcional |
+| ---------- | -------- |
+| `Name`     | Não      |
+| `Value`    | Não      |
+| `Path`     | Sim      |
+| `Domain`   | Sim      |
+| `Expires`  | Sim      |
+| `Secure`   | Sim      |
+| `HttpOnly` | Sim      |
+
+## Criar um cookie
+
+```go
+func writeCookie(c *echo.Context) error {
+	cookie := new(http.Cookie)
+	cookie.Name = "username"
+	cookie.Value = "jon"
+	cookie.Expires = time.Now().Add(24 * time.Hour)
+	c.SetCookie(cookie)
+	return c.String(http.StatusOK, "write a cookie")
+}
+```
+
+- Crie o cookie com `new(http.Cookie)`.
+- Defina atributos nos campos de `http.Cookie`.
+- Chame `c.SetCookie(cookie)` para adicionar um header `Set-Cookie` à response.
+
+## Ler um cookie
+
+```go
+func readCookie(c *echo.Context) error {
+	cookie, err := c.Cookie("username")
+	if err != nil {
+		return err
+	}
+	fmt.Println(cookie.Name)
+	fmt.Println(cookie.Value)
+	return c.String(http.StatusOK, "read a cookie")
+}
+```
+
+- Leia um cookie por nome com `c.Cookie("username")`.
+- Acesse seus atributos por meio dos campos de `http.Cookie`.
+
+## Ler todos os cookies
+
+```go
+func readAllCookies(c *echo.Context) error {
+	for _, cookie := range c.Cookies() {
+		fmt.Println(cookie.Name)
+		fmt.Println(cookie.Value)
+	}
+	return c.String(http.StatusOK, "read all the cookies")
+}
+```

site/src/content/docs/pt-br/guide/customization.md

@@ -0,0 +1,63 @@
+---
+title: Customização
+description: Customize logger, validator, binder, renderer, serializer e tratamento de erros do Echo.
+sidebar:
+  order: 12
+---
+
+Echo expõe um conjunto de campos na instância `Echo` que permite substituir o comportamento
+embutido pelas suas próprias implementações.
+
+## Logging
+
+`Echo#Logger` escreve logs estruturados. O handler padrão emite JSON para `os.Stdout`.
+
+### Logger customizado
+
+O logger é um `*slog.Logger`, então você pode registrar qualquer handler `slog`:
+
+```go
+e.Logger = slog.New(slog.NewJSONHandler(os.Stdout, nil))
+```
+
+## Validator
+
+`Echo#Validator` registra um validador para validação de payloads de request.
+
+[Saiba mais](/pt-br/guide/request/#validate-data)
+
+## Binder customizado
+
+`Echo#Binder` registra um binder customizado para binding de payloads de request.
+
+[Saiba mais](/pt-br/guide/binding/#custom-binder)
+
+## Serializer JSON customizado
+
+`Echo#JSONSerializer` registra um serializer JSON customizado. Veja `DefaultJSONSerializer`
+em [json.go](https://github.com/labstack/echo/blob/master/json.go).
+
+## Renderer
+
+`Echo#Renderer` registra um renderer para renderização de templates.
+
+[Saiba mais](/pt-br/guide/templates/)
+
+## Handler de erro HTTP
+
+`Echo#HTTPErrorHandler` registra um handler de erro HTTP customizado.
+
+[Saiba mais](/pt-br/guide/error-handling/)
+
+## Callback de rota
+
+`Echo#OnAddRoute` registra um callback chamado sempre que uma nova rota é adicionada ao
+router.
+
+## Extrator de IP
+
+`Echo#IPExtractor` controla como o endereço IP real do cliente é determinado. Para
+recuperá-lo de forma confiável e segura, sua aplicação precisa conhecer toda a sua
+infraestrutura.
+
+[Saiba mais](/pt-br/guide/ip-address/)