docs-i18n 0.8.1 → 0.8.3

package/template/content/form/en/quick-start.md

@@ -0,0 +1,121 @@
+---
+title: Quick Start
+description: Get up and running with TanStack Form
+---
+
+# Quick Start
+
+## Create a Form
+
+Use the `useForm` hook to create a form instance:
+
+```tsx
+import { useForm } from '@tanstack/react-form'
+
+function MyForm() {
+  const form = useForm({
+    defaultValues: {
+      username: '',
+      password: '',
+    },
+    onSubmit: async ({ value }) => {
+      // Handle form submission
+      await loginUser(value)
+    },
+  })
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault()
+        form.handleSubmit()
+      }}
+    >
+      {/* Fields go here */}
+      <button type="submit">Submit</button>
+    </form>
+  )
+}
+```
+
+## Add Fields
+
+Use `form.Field` to create type-safe form fields:
+
+```tsx
+<form.Field name="username">
+  {(field) => (
+    <div>
+      <label htmlFor={field.name}>Username</label>
+      <input
+        id={field.name}
+        value={field.state.value}
+        onBlur={field.handleBlur}
+        onChange={(e) => field.handleChange(e.target.value)}
+      />
+    </div>
+  )}
+</form.Field>
+```
+
+## Add Validation
+
+Add field-level validation with sync or async validators:
+
+```tsx
+<form.Field
+  name="email"
+  validators={{
+    onChange: ({ value }) => {
+      if (!value) return 'Email is required'
+      if (!value.includes('@')) return 'Invalid email address'
+      return undefined
+    },
+    onChangeAsyncDebounceMs: 500,
+    onChangeAsync: async ({ value }) => {
+      const exists = await checkEmailExists(value)
+      return exists ? 'Email already taken' : undefined
+    },
+  }}
+>
+  {(field) => (
+    <div>
+      <input
+        value={field.state.value}
+        onChange={(e) => field.handleChange(e.target.value)}
+      />
+      {field.state.meta.errors.map((error) => (
+        <p key={error} className="text-red-500">{error}</p>
+      ))}
+    </div>
+  )}
+</form.Field>
+```
+
+## Using Zod Validation
+
+```tsx
+import { zodValidator } from '@tanstack/zod-form-adapter'
+import { z } from 'zod'
+
+const form = useForm({
+  defaultValues: { email: '' },
+  validatorAdapter: zodValidator(),
+  onSubmit: async ({ value }) => {
+    console.log(value)
+  },
+})
+
+// Then in your field:
+<form.Field
+  name="email"
+  validators={{
+    onChange: z.string().email('Invalid email'),
+  }}
+>
+  {(field) => /* ... */}
+</form.Field>
+```
+
+> [!NOTE]
+> Async validators support debouncing out of the box with `onChangeAsyncDebounceMs`.

package/template/content/form/ja/installation.md

@@ -0,0 +1,63 @@
+---
+title: インストール
+description: プロジェクトに TanStack Form をインストールする方法
+---
+
+# インストール
+
+## React
+
+```bash
+npm install @tanstack/react-form
+```
+
+```bash
+pnpm add @tanstack/react-form
+```
+
+```bash
+yarn add @tanstack/react-form
+```
+
+```bash
+bun add @tanstack/react-form
+```
+
+## Vue
+
+```bash
+npm install @tanstack/vue-form
+```
+
+## Angular
+
+```bash
+npm install @tanstack/angular-form
+```
+
+## バリデーションアダプター
+
+TanStack Form はアダプターを通じて人気のバリデーションライブラリをサポートしています：
+
+### Zod
+
+```bash
+npm install @tanstack/zod-form-adapter zod
+```
+
+### Valibot
+
+```bash
+npm install @tanstack/valibot-form-adapter valibot
+```
+
+### Yup
+
+```bash
+npm install @tanstack/yup-form-adapter yup
+```
+
+## 必要要件
+
+- TypeScript 5.0+
+- React 18+ / Vue 3+ / Angular 17+

package/template/content/form/ja/overview.md

@@ -0,0 +1,71 @@
+---
+title: TanStack Form 概要
+description: ヘッドレスで高性能、型安全なフォーム状態管理
+---
+
+# TanStack Form
+
+TanStack Form は、TS/JS、React、Vue、Angular 向けのヘッドレスで高性能、型安全なフォーム状態管理ライブラリです。
+
+## なぜ TanStack Form を選ぶのか？
+
+ほとんどのフォームライブラリは、利便性のために型安全性を犠牲にするか、特定のフレームワークに密結合しています。TanStack Form はその両方を実現します。フォームの値からバリデーションエラーまで完全な型安全性を提供し、React、Vue、Angular のアダプターを備えています。
+
+## 特徴
+
+- **型安全** — フォームの値、フィールド名、バリデーションの完全な TypeScript 推論
+- **フレームワーク非依存** — React、Vue、Angular などで動作
+- **ヘッドレス** — UI の制約なし、独自のコンポーネントを使用
+- **高性能** — フィールドレベルのサブスクリプション、不要な再レンダリングなし
+- **バリデーション** — 組み込みの同期・非同期バリデーション、Zod、Valibot、Yup アダプターをサポート
+- **配列と動的フィールド** — 配列フィールドのファーストクラスサポート
+
+## 基本的な例
+
+```tsx
+import { useForm } from '@tanstack/react-form'
+
+function SignupForm() {
+  const form = useForm({
+    defaultValues: {
+      firstName: '',
+      lastName: '',
+      email: '',
+    },
+    onSubmit: async ({ value }) => {
+      console.log(value)
+    },
+  })
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault()
+        form.handleSubmit()
+      }}
+    >
+      <form.Field
+        name="firstName"
+        validators={{
+          onChange: ({ value }) =>
+            !value ? 'First name is required' : undefined,
+        }}
+      >
+        {(field) => (
+          <div>
+            <label>First Name</label>
+            <input
+              value={field.state.value}
+              onChange={(e) => field.handleChange(e.target.value)}
+            />
+            {field.state.meta.errors.length > 0 && (
+              <span>{field.state.meta.errors.join(', ')}</span>
+            )}
+          </div>
+        )}
+      </form.Field>
+      <button type="submit">Submit</button>
+    </form>
+  )
+}
+```

package/template/content/form/zh-hans/installation.md

@@ -0,0 +1,63 @@
+---
+title: 安装
+description: 如何在项目中安装 TanStack Form
+---
+
+# 安装
+
+## React
+
+```bash
+npm install @tanstack/react-form
+```
+
+```bash
+pnpm add @tanstack/react-form
+```
+
+```bash
+yarn add @tanstack/react-form
+```
+
+```bash
+bun add @tanstack/react-form
+```
+
+## Vue
+
+```bash
+npm install @tanstack/vue-form
+```
+
+## Angular
+
+```bash
+npm install @tanstack/angular-form
+```
+
+## 验证适配器
+
+TanStack Form 通过适配器支持流行的验证库：
+
+### Zod
+
+```bash
+npm install @tanstack/zod-form-adapter zod
+```
+
+### Valibot
+
+```bash
+npm install @tanstack/valibot-form-adapter valibot
+```
+
+### Yup
+
+```bash
+npm install @tanstack/yup-form-adapter yup
+```
+
+## 环境要求
+
+- TypeScript 5.0+
+- React 18+ / Vue 3+ / Angular 17+

package/template/content/form/zh-hans/overview.md

@@ -0,0 +1,71 @@
+---
+title: TanStack Form 概览
+description: 无头、高性能、类型安全的表单状态管理
+---
+
+# TanStack Form
+
+TanStack Form 是一个无头、高性能、类型安全的表单状态管理库，支持 TS/JS、React、Vue 和 Angular。
+
+## 为什么选择 TanStack Form？
+
+大多数表单库要么为了便利牺牲了类型安全，要么与特定框架紧密耦合。TanStack Form 两者兼顾——从表单值到验证错误的完整类型安全，并提供 React、Vue 和 Angular 的适配器。
+
+## 特性
+
+- **类型安全** — 表单值、字段名称和验证的完整 TypeScript 推断
+- **框架无关** — 支持 React、Vue、Angular 等
+- **无头** — 无 UI 限制，使用你自己的组件
+- **高性能** — 字段级订阅，无不必要的重渲染
+- **验证** — 内置同步和异步验证，支持 Zod、Valibot 和 Yup 适配器
+- **数组和动态字段** — 一流的数组字段支持
+
+## 基本示例
+
+```tsx
+import { useForm } from '@tanstack/react-form'
+
+function SignupForm() {
+  const form = useForm({
+    defaultValues: {
+      firstName: '',
+      lastName: '',
+      email: '',
+    },
+    onSubmit: async ({ value }) => {
+      console.log(value)
+    },
+  })
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault()
+        form.handleSubmit()
+      }}
+    >
+      <form.Field
+        name="firstName"
+        validators={{
+          onChange: ({ value }) =>
+            !value ? 'First name is required' : undefined,
+        }}
+      >
+        {(field) => (
+          <div>
+            <label>First Name</label>
+            <input
+              value={field.state.value}
+              onChange={(e) => field.handleChange(e.target.value)}
+            />
+            {field.state.meta.errors.length > 0 && (
+              <span>{field.state.meta.errors.join(', ')}</span>
+            )}
+          </div>
+        )}
+      </form.Field>
+      <button type="submit">Submit</button>
+    </form>
+  )
+}
+```

package/template/content/query/docs.config.json

@@ -0,0 +1,32 @@
+{
+  "sections": [
+    {
+      "label": "Getting Started",
+      "children": [
+        { "label": "Overview", "to": "overview" },
+        { "label": "Installation", "to": "installation" },
+        { "label": "Quick Start", "to": "quick-start" }
+      ]
+    },
+    {
+      "label": "Guides",
+      "children": [
+        { "label": "Queries", "to": "guides/queries" },
+        { "label": "Pagination", "to": "guides/pagination" },
+        { "label": "Mutations", "to": "guides/mutations" }
+      ]
+    },
+    {
+      "label": "React",
+      "frameworks": [
+        {
+          "label": "React",
+          "children": [
+            { "label": "Overview", "to": "overview" },
+            { "label": "Quick Start", "to": "quick-start" }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/template/content/query/en/guides/mutations.md

@@ -0,0 +1,126 @@
+---
+title: Mutations
+description: Learn how to create, update, and delete data with TanStack Query mutations
+---
+
+# Mutations
+
+Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. For this purpose, TanStack Query exports a `useMutation` hook.
+
+## Basic Mutation
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+function AddTodo() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: (newTodo: { title: string }) => {
+      return fetch('/api/todos', {
+        method: 'POST',
+        body: JSON.stringify(newTodo),
+        headers: { 'Content-Type': 'application/json' },
+      }).then((res) => res.json())
+    },
+    onSuccess: () => {
+      // Invalidate and refetch the todos list
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button
+      onClick={() => mutation.mutate({ title: 'New Todo' })}
+      disabled={mutation.isPending}
+    >
+      {mutation.isPending ? 'Adding...' : 'Add Todo'}
+    </button>
+  )
+}
+```
+
+## Mutation States
+
+A mutation can only be in one of the following states at any given moment:
+
+| State | Description |
+|---|---|
+| `isIdle` | The mutation is idle or in a fresh/reset state |
+| `isPending` | The mutation is currently running |
+| `isError` | The mutation encountered an error |
+| `isSuccess` | The mutation was successful and data is available |
+
+## Optimistic Updates
+
+Optimistic updates allow you to update the UI before the server confirms the mutation, providing a snappier user experience:
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // Cancel any outgoing refetches to avoid overwriting optimistic update
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+    // Snapshot the previous value
+    const previousTodos = queryClient.getQueryData(['todos'])
+
+    // Optimistically update to the new value
+    queryClient.setQueryData(['todos'], (old: Todo[]) => [
+      ...old,
+      { ...newTodo, id: Date.now() },
+    ])
+
+    // Return a context object with the snapshotted value
+    return { previousTodos }
+  },
+  onError: (_err, _newTodo, context) => {
+    // Roll back to the previous value on error
+    queryClient.setQueryData(['todos'], context?.previousTodos)
+  },
+  onSettled: () => {
+    // Always refetch after error or success
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+> [!NOTE]
+> The `onMutate` handler runs before the mutation function and receives the same variables. It is the perfect place to perform optimistic updates.
+
+## Retry
+
+By default, TanStack Query will not retry failed mutations. You can configure this per-mutation:
+
+```tsx
+const mutation = useMutation({
+  mutationFn: addTodo,
+  retry: 3, // Retry failed mutations 3 times
+})
+```
+
+## Mutation Callbacks
+
+The `useMutation` hook supports several callback options:
+
+```tsx
+useMutation({
+  mutationFn: addTodo,
+  onMutate: (variables) => {
+    // Called before the mutation function fires
+    // Receives the same variables the mutation function would receive
+  },
+  onError: (error, variables, context) => {
+    // Called if the mutation encounters an error
+  },
+  onSuccess: (data, variables, context) => {
+    // Called if the mutation is successful
+  },
+  onSettled: (data, error, variables, context) => {
+    // Called regardless of success or error
+  },
+})
+```
+
+> [!WARNING]
+> The callbacks on `useMutation` fire for every component instance that uses it. To ensure side-effects only run once, use the callbacks on the `mutate` function or move the mutation to a shared hook.

package/template/content/query/en/guides/pagination.md

@@ -0,0 +1,98 @@
+---
+title: Pagination
+description: Learn how to implement paginated queries with TanStack Query
+---
+
+# Pagination
+
+Rendering paginated data is a very common UI pattern and in TanStack Query, it "just works" by including the page information in the query key.
+
+## Basic Pagination Example
+
+```tsx
+const fetchProjects = async (page: number) => {
+  const res = await fetch(`/api/projects?page=${page}`)
+  return res.json()
+}
+
+function Projects() {
+  const [page, setPage] = React.useState(1)
+
+  const { data, isPreviousData, isLoading } = useQuery({
+    queryKey: ['projects', page],
+    queryFn: () => fetchProjects(page),
+    placeholderData: keepPreviousData,
+  })
+
+  return (
+    <div>
+      {isLoading ? (
+        <div>Loading...</div>
+      ) : (
+        <>
+          {data.projects.map((project) => (
+            <p key={project.id}>{project.name}</p>
+          ))}
+        </>
+      )}
+      <div className="flex gap-2">
+        <button
+          onClick={() => setPage((old) => Math.max(old - 1, 1))}
+          disabled={page === 1}
+        >
+          Previous
+        </button>
+        <span>Page {page}</span>
+        <button
+          onClick={() => {
+            if (!isPreviousData && data.hasMore) {
+              setPage((old) => old + 1)
+            }
+          }}
+          disabled={isPreviousData || !data?.hasMore}
+        >
+          Next
+        </button>
+      </div>
+    </>
+  )
+}
+```
+
+## Using `keepPreviousData`
+
+The `keepPreviousData` option is crucial for smooth pagination. When enabled, the data from the last successful fetch is available while new data is being requested, even when the query key changes.
+
+> [!NOTE]
+> `keepPreviousData` was renamed from `previousData` in v5. If you are migrating from v4, update your code accordingly.
+
+## Prefetching Next Pages
+
+For an even smoother UX, you can prefetch the next page before the user navigates to it:
+
+```tsx
+const queryClient = useQueryClient()
+
+React.useEffect(() => {
+  if (data?.hasMore) {
+    queryClient.prefetchQuery({
+      queryKey: ['projects', page + 1],
+      queryFn: () => fetchProjects(page + 1),
+    })
+  }
+}, [data, page, queryClient])
+```
+
+## Infinite Queries
+
+For "load more" and infinite scroll patterns, TanStack Query provides the `useInfiniteQuery` hook. See the [Infinite Queries guide](/en/query/docs/guides/infinite-queries) for details.
+
+| Feature | `useQuery` + pagination | `useInfiniteQuery` |
+|---|---|---|
+| Page navigation | Previous / Next buttons | Load More / Infinite Scroll |
+| Data structure | Single page | Accumulated pages |
+| Memory usage | Lower (one page) | Higher (all loaded pages) |
+| URL sync | Easy | More complex |
+
+> [!WARNING]
+> Do not use `useInfiniteQuery` for traditional page-based navigation. It is designed for "load more" patterns where previously loaded data stays visible.