docs(i18n): guide (zh-cn, ja)

Author: vishr

site/src/content/docs/ja/guide/binding.md

@@ -0,0 +1,154 @@
+---
+title: バインディング
+description: パス、クエリ、header、リクエストボディからリクエストデータを型付き Go struct に解析します。
+sidebar:
+  order: 5
+---
+
+リクエストデータの解析は、Web アプリケーションの重要な要素です。Echo ではこれを
+_バインディング_ と呼び、HTTP リクエストの 4 つの部分から読み取れます。
+
+- URL パスパラメーター
+- URL クエリパラメーター
+- Header
+- リクエストボディ
+
+## Struct タグによるバインディング
+
+データソースとキーを指定するタグ付きの struct を定義し、そのポインターを
+`c.Bind()` に渡します。ここではクエリパラメーター `id` が `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")
+}
+```
+
+### データソース
+
+| タグ     | ソース |
+| -------- | ------ |
+| `query`  | クエリパラメーター |
+| `param`  | パスパラメーター |
+| `header` | Header 値 |
+| `form`   | フォームデータ（クエリ + ボディ） |
+| `json`   | リクエストボディ（`encoding/json`） |
+| `xml`    | リクエストボディ（`encoding/xml`） |
+
+パス、クエリ、header、フォームのフィールドには**明示的なタグ**が必要です。
+JSON と XML はタグが省略された場合、標準ライブラリと同じように struct フィールド名へ
+フォールバックします。
+
+### ボディのコンテンツタイプ
+
+リクエストボディをデコードするときは、`Content-Type` header によってデコーダーが選ばれます。
+
+- `application/json`
+- `application/xml`
+- `application/x-www-form-urlencoded`
+
+### 複数ソースと優先順位
+
+1 つのフィールドで複数のソースを宣言できます。データは次の順序でバインドされ、
+各ステップが前の値を上書きします。
+
+1. パスパラメーター
+2. クエリパラメーター（GET / DELETE のみ）
+3. リクエストボディ
+
+```go
+type User struct {
+	ID string `param:"id" query:"id" form:"id" json:"id" xml:"id"`
+}
+```
+
+### 1 つのソースから直接バインドする
+
+```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
+Header は `c.Bind()` に**含まれません**。`echo.BindHeaders` で直接バインドしてください。
+:::
+
+:::caution[セキュリティ]
+ビジネス用の struct に直接バインドしないでください。バインド対象の struct が
+`IsAdmin bool` フィールドを公開している場合、`{"IsAdmin": true}` というリクエストボディで
+その値が設定されます。専用の DTO を使い、明示的にマッピングしてください。
+:::
+
+```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)
+})
+```
+
+## フルーエントバインディング
+
+単一ソースから明示的かつ型安全にバインドするには、フルーエント binder を使います。
+設定をチェーンし、実行時にエラーを収集します。
+
+```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
+```
+
+利用できる binder は `echo.QueryParamsBinder(c)`、`echo.PathValuesBinder(c)`、
+`echo.FormFieldBinder(c)` です。チェーンは `BindError()`（最初のエラー）または
+`BindErrors()`（すべてのエラー）で終了します。`FailFast(false)` はチェーン全体を実行します。
+デフォルトでは早期終了が有効です。
+
+各サポート型には `Type(...)`、`MustType(...)`、`Types(...)`（スライス）、
+`MustTypes(...)` メソッドがあります。例：`Int64`、`MustInt64`、`Int64s`。
+カンマ区切りの値を分割するには `BindWithDelimiter("id", &dest, ",")` を使います。
+
+## カスタム binder
+
+`Echo#Binder` でカスタム 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/ja/guide/context.md

@@ -0,0 +1,80 @@
+---
+title: コンテキスト
+description: リクエスト、レスポンス、パラメーター、ヘルパーを保持するリクエストごとのオブジェクトです。
+sidebar:
+  order: 4
+---
+
+`echo.Context` は現在の HTTP リクエストのコンテキストを表します。そのポインター
+（`*echo.Context`）はすべてのハンドラとミドルウェアに渡され、リクエストとレスポンス、
+パスパラメーター、バインド済みデータ、レスポンス作成用のヘルパーを保持します。
+
+```go
+func handler(c *echo.Context) error {
+	// ...
+	return nil
+}
+```
+
+## 入力を読む
+
+```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)
+```
+
+値が存在しない場合にデフォルト値を返す、対応する `*Or` ヘルパーもあります。
+`c.ParamOr("id", "0")`、`c.QueryParamOr("page", "1")`、`c.FormValueOr(...)`
+などです。
+
+## レスポンスを書く
+
+```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")
+```
+
+## ファイル
+
+```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
+```
+
+## リクエストごとのストレージ
+
+`Get`/`Set` を使ってミドルウェアとハンドラの間でデータを共有します。
+
+```go
+c.Set("user", u)
+u, _ := c.Get("user").(*User)
+```
+
+ジェネリクスヘルパーで型付きアクセスもできます。
+
+```go
+u, err := echo.ContextGet[*User](c, "user")
+```
+
+## バインディングと検証
+
+`c.Bind()` はリクエストデータを struct に解析します。詳しくは
+[バインディング](/ja/guide/binding/)を参照してください。
+
+```go
+var dto CreateUser
+if err := c.Bind(&dto); err != nil {
+	return echo.ErrBadRequest
+}
+```

site/src/content/docs/ja/guide/cookies.md

@@ -0,0 +1,71 @@
+---
+title: Cookie
+description: 標準の http.Cookie 型を使って HTTP Cookie を作成、読み取り、一覧表示します。
+sidebar:
+  order: 11
+---
+
+Cookie はサーバーがブラウザーに送信する小さなデータで、ブラウザーはそれを保存し、
+後続のリクエストで送り返します。Cookie により、ショッピングカート、認証状態、
+以前入力したフォーム値などの状態を Web サイトが記憶できます。
+
+Echo は Go 標準の `http.Cookie` 型を使い、ハンドラ内の `echo.Context` から
+Cookie を追加および取得します。
+
+## Cookie 属性
+
+| 属性       | 任意 |
+| ---------- | ---- |
+| `Name`     | いいえ |
+| `Value`    | いいえ |
+| `Path`     | はい |
+| `Domain`   | はい |
+| `Expires`  | はい |
+| `Secure`   | はい |
+| `HttpOnly` | はい |
+
+## 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")
+}
+```
+
+- `new(http.Cookie)` で Cookie を作成します。
+- `http.Cookie` フィールドに属性を設定します。
+- `c.SetCookie(cookie)` を呼び出して、レスポンスに `Set-Cookie` header を追加します。
+
+## 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")
+}
+```
+
+- `c.Cookie("username")` で名前から Cookie を読み取ります。
+- `http.Cookie` フィールドを通じて属性にアクセスします。
+
+## すべての Cookie を読む
+
+```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/ja/guide/customization.md

@@ -0,0 +1,64 @@
+---
+title: カスタマイズ
+description: Echo の logger、validator、binder、renderer、serializer、エラー処理をカスタマイズします。
+sidebar:
+  order: 12
+---
+
+Echo は `Echo` インスタンス上に一連のフィールドを公開しており、組み込みの挙動を
+独自実装に置き換えられます。
+
+## ログ
+
+`Echo#Logger` は構造化ログを書き込みます。デフォルトのハンドラは JSON を
+`os.Stdout` に出力します。
+
+### カスタム logger
+
+logger は `*slog.Logger` なので、任意の `slog` ハンドラを登録できます。
+
+```go
+e.Logger = slog.New(slog.NewJSONHandler(os.Stdout, nil))
+```
+
+## Validator
+
+`Echo#Validator` はリクエストペイロード検証用の validator を登録します。
+
+[詳しく見る](/ja/guide/request/#validate-data)
+
+## カスタム binder
+
+`Echo#Binder` はリクエストペイロードをバインドするカスタム binder を登録します。
+
+[詳しく見る](/ja/guide/binding/#custom-binder)
+
+## カスタム JSON serializer
+
+`Echo#JSONSerializer` はカスタム JSON serializer を登録します。
+[json.go](https://github.com/labstack/echo/blob/master/json.go) の
+`DefaultJSONSerializer` を参照してください。
+
+## Renderer
+
+`Echo#Renderer` はテンプレートレンダリング用の renderer を登録します。
+
+[詳しく見る](/ja/guide/templates/)
+
+## HTTP エラーハンドラ
+
+`Echo#HTTPErrorHandler` はカスタム HTTP エラーハンドラを登録します。
+
+[詳しく見る](/ja/guide/error-handling/)
+
+## ルートコールバック
+
+`Echo#OnAddRoute` は、新しいルートがルーターに追加されるたびに呼び出される
+コールバックを登録します。
+
+## IP 抽出器
+
+`Echo#IPExtractor` は実際のクライアント IP アドレスをどう判定するかを制御します。
+信頼性と安全性を保って取得するには、アプリケーションがインフラ全体を把握している必要があります。
+
+[詳しく見る](/ja/guide/ip-address/)