docs-i18n 0.8.1 → 0.8.3

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

@@ -0,0 +1,120 @@
+---
+title: Queries
+description: Learn how queries work in TanStack Query
+---
+
+# Queries
+
+A query is a declarative dependency on an asynchronous source of data that is tied to a unique key. A query can be used with any Promise-based method (including GET and POST methods) to fetch data from a server.
+
+## Query Basics
+
+To subscribe to a query in your components, call the query hook with at least a unique key and a function that returns a promise:
+
+<!-- ::start:react -->
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function Example() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodoList,
+  })
+}
+```
+
+<!-- ::end:react -->
+
+<!-- ::start:vue -->
+
+```vue
+<script setup>
+import { useQuery } from '@tanstack/vue-query'
+
+const { data, isLoading, error } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodoList,
+})
+</script>
+```
+
+<!-- ::end:vue -->
+
+<!-- ::start:solid -->
+
+```tsx
+import { createQuery } from '@tanstack/solid-query'
+
+function Example() {
+  const query = createQuery(() => ({
+    queryKey: ['todos'],
+    queryFn: fetchTodoList,
+  }))
+}
+```
+
+<!-- ::end:solid -->
+
+## Query Keys
+
+Query keys are used to uniquely identify a query. They can be as simple as a string, or as complex as an array of many strings and nested objects:
+
+```ts
+// A simple string key
+useQuery({ queryKey: ['todos'], ... })
+
+// A key with variables
+useQuery({ queryKey: ['todo', todoId], ... })
+
+// A key with an object
+useQuery({ queryKey: ['todos', { type: 'done', page: 1 }], ... })
+```
+
+## Query Functions
+
+A query function can be literally any function that returns a promise. The promise that is returned should either resolve the data or throw an error:
+
+```ts
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: async () => {
+    const response = await fetch('/api/todos')
+    if (!response.ok) {
+      throw new Error('Network response was not ok')
+    }
+    return response.json()
+  },
+})
+```
+
+## Query States
+
+A query can be in one of the following states at any given moment:
+
+- **`isPending`** — The query has no data yet
+- **`isError`** — The query encountered an error
+- **`isSuccess`** — The query was successful and data is available
+
+```tsx
+function Todos() {
+  const { data, isPending, isError, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  if (isPending) return <span>Loading...</span>
+  if (isError) return <span>Error: {error.message}</span>
+
+  return (
+    <ul>
+      {data.map((todo) => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+> [!NOTE]
+> In TanStack Query v5, `isLoading` has been renamed to `isPending` for consistency.

package/template/content/query/en/installation.md

@@ -0,0 +1,78 @@
+---
+title: Installation
+description: How to install TanStack Query in your project
+---
+
+# Installation
+
+TanStack Query is available as a package on npm for each supported framework.
+
+## Install the Package
+
+Choose the package for your framework:
+
+### React
+
+```bash
+npm install @tanstack/react-query
+```
+
+```bash
+pnpm add @tanstack/react-query
+```
+
+```bash
+yarn add @tanstack/react-query
+```
+
+```bash
+bun add @tanstack/react-query
+```
+
+### Vue
+
+```bash
+npm install @tanstack/vue-query
+```
+
+### Solid
+
+```bash
+npm install @tanstack/solid-query
+```
+
+### Svelte
+
+```bash
+npm install @tanstack/svelte-query
+```
+
+### Angular
+
+```bash
+npm install @tanstack/angular-query-experimental
+```
+
+## Requirements
+
+- TypeScript 4.7+ (for type inference)
+- React 18+ / Vue 3+ / Solid 1.6+ / Svelte 4+
+
+## Devtools
+
+We recommend also installing the devtools for a better development experience:
+
+```bash
+npm install @tanstack/react-query-devtools
+```
+
+> [!NOTE]
+> Devtools are currently only available for React. Community devtools exist for other frameworks.
+
+## CDN
+
+For prototyping, you can load TanStack Query from a CDN:
+
+```html
+<script src="https://unpkg.com/@tanstack/react-query/build/umd/index.production.js"></script>
+```

package/template/content/query/en/overview.md

@@ -0,0 +1,72 @@
+---
+title: TanStack Query Overview
+description: Powerful asynchronous state management for TS/JS, React, Vue, Solid, Svelte & Angular
+---
+
+# TanStack Query
+
+TanStack Query (formerly React Query) makes fetching, caching, synchronizing, and updating server state in your web applications a breeze.
+
+## Motivation
+
+Most core web frameworks do not come with an opinionated way of fetching or updating data in a holistic way. Developers end up building either meta-frameworks which encapsulate strict opinions about data-fetching, or they invent their own ways of fetching data. This usually means cobbling together component-based state and side-effects, or using more general purpose state management libraries to store and provide asynchronous data throughout their apps.
+
+## Features
+
+- **Transport/protocol/backend agnostic** data fetching (REST, GraphQL, promises, whatever!)
+- **Auto Caching** with request deduplication
+- **Automatic Refetching** with stale-while-revalidate strategy
+- **Window Focus Refetching** to keep data current
+- **Polling/Realtime** queries with configurable intervals
+- **Parallel & Dependent Queries** for complex data requirements
+- **Mutations** with optimistic updates
+- **Pagination & Infinite Scroll** out of the box
+- **Dedicated Devtools** for debugging
+
+## Supported Frameworks
+
+TanStack Query supports the following frameworks:
+
+```ts
+// React
+import { useQuery } from '@tanstack/react-query'
+
+// Vue
+import { useQuery } from '@tanstack/vue-query'
+
+// Solid
+import { createQuery } from '@tanstack/solid-query'
+
+// Svelte
+import { createQuery } from '@tanstack/svelte-query'
+
+// Angular
+import { injectQuery } from '@tanstack/angular-query-experimental'
+```
+
+## Quick Example
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function App() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: () => fetch('/api/todos').then(res => res.json()),
+  })
+
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+
+  return (
+    <ul>
+      {data.map(todo => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+> [!NOTE]
+> TanStack Query v5 is the latest version and includes significant improvements over v4 including a simplified API and better TypeScript support.

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

@@ -0,0 +1,108 @@
+---
+title: Quick Start
+description: Get up and running with TanStack Query in minutes
+---
+
+# Quick Start
+
+This guide will help you get started with TanStack Query as quickly as possible.
+
+## Set Up the Provider
+
+Wrap your application with `QueryClientProvider` and pass a `QueryClient` instance:
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const queryClient = new QueryClient()
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <MyApp />
+    </QueryClientProvider>
+  )
+}
+```
+
+## Your First Query
+
+Use the `useQuery` hook to fetch data:
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function Todos() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  if (isLoading) return <span>Loading...</span>
+  if (error) return <span>Error: {error.message}</span>
+
+  return (
+    <ul>
+      {data.map((todo) => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+
+async function fetchTodos() {
+  const res = await fetch('https://jsonplaceholder.typicode.com/todos')
+  if (!res.ok) throw new Error('Failed to fetch')
+  return res.json()
+}
+```
+
+## Your First Mutation
+
+Use `useMutation` to create, update, or delete data:
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+function AddTodo() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: (newTodo: { title: string }) =>
+      fetch('/api/todos', {
+        method: 'POST',
+        body: JSON.stringify(newTodo),
+      }).then((res) => res.json()),
+    onSuccess: () => {
+      // Invalidate and refetch
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button onClick={() => mutation.mutate({ title: 'New Todo' })}>
+      Add Todo
+    </button>
+  )
+}
+```
+
+## Adding Devtools
+
+Add the React Query Devtools for debugging:
+
+```tsx
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <MyApp />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  )
+}
+```
+
+> [!NOTE]
+> Devtools are automatically excluded from production builds.

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

@@ -0,0 +1,78 @@
+---
+title: インストール
+description: プロジェクトに TanStack Query をインストールする方法
+---
+
+# インストール
+
+TanStack Query は、サポートされている各フレームワーク向けの npm パッケージとして利用できます。
+
+## パッケージのインストール
+
+フレームワークに合わせたパッケージを選択してください：
+
+### React
+
+```bash
+npm install @tanstack/react-query
+```
+
+```bash
+pnpm add @tanstack/react-query
+```
+
+```bash
+yarn add @tanstack/react-query
+```
+
+```bash
+bun add @tanstack/react-query
+```
+
+### Vue
+
+```bash
+npm install @tanstack/vue-query
+```
+
+### Solid
+
+```bash
+npm install @tanstack/solid-query
+```
+
+### Svelte
+
+```bash
+npm install @tanstack/svelte-query
+```
+
+### Angular
+
+```bash
+npm install @tanstack/angular-query-experimental
+```
+
+## 必要要件
+
+- TypeScript 4.7+（型推論のため）
+- React 18+ / Vue 3+ / Solid 1.6+ / Svelte 4+
+
+## Devtools
+
+より良い開発体験のために、devtools のインストールもお勧めします：
+
+```bash
+npm install @tanstack/react-query-devtools
+```
+
+> [!NOTE]
+> Devtools は現在 React のみ対応しています。他のフレームワーク向けにはコミュニティ製の devtools があります。
+
+## CDN
+
+プロトタイピングには、CDN から TanStack Query を読み込めます：
+
+```html
+<script src="https://unpkg.com/@tanstack/react-query/build/umd/index.production.js"></script>
+```

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

@@ -0,0 +1,72 @@
+---
+title: TanStack Query 概要
+description: TS/JS、React、Vue、Solid、Svelte、Angular向けの強力な非同期状態管理
+---
+
+# TanStack Query
+
+TanStack Query（旧称 React Query）を使えば、Webアプリケーションにおけるデータの取得、キャッシュ、同期、更新が簡単に行えます。
+
+## モチベーション
+
+ほとんどのWebフレームワークには、データの取得や更新について統一的な方法が用意されていません。開発者は独自のデータ取得方法を考案するか、メタフレームワークを構築する必要があります。これは通常、コンポーネントベースの状態と副作用を組み合わせるか、汎用的な状態管理ライブラリを使って非同期データを管理することを意味します。
+
+## 特徴
+
+- **トランスポート/プロトコル/バックエンド非依存** のデータ取得（REST、GraphQL、Promiseなど何でも対応！）
+- **自動キャッシュ** とリクエストの重複排除
+- **自動再取得** — stale-while-revalidate戦略
+- **ウィンドウフォーカス再取得** でデータを最新に保つ
+- **ポーリング/リアルタイム** クエリ（間隔設定可能）
+- **並列・依存クエリ** で複雑なデータ要件に対応
+- **ミューテーション** — 楽観的更新をサポート
+- **ページネーション・無限スクロール** を標準サポート
+- **専用DevTools** でデバッグを支援
+
+## サポートされるフレームワーク
+
+TanStack Queryは以下のフレームワークをサポートしています：
+
+```ts
+// React
+import { useQuery } from '@tanstack/react-query'
+
+// Vue
+import { useQuery } from '@tanstack/vue-query'
+
+// Solid
+import { createQuery } from '@tanstack/solid-query'
+
+// Svelte
+import { createQuery } from '@tanstack/svelte-query'
+
+// Angular
+import { injectQuery } from '@tanstack/angular-query-experimental'
+```
+
+## クイック例
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function App() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: () => fetch('/api/todos').then(res => res.json()),
+  })
+
+  if (isLoading) return <div>読み込み中...</div>
+  if (error) return <div>エラー：{error.message}</div>
+
+  return (
+    <ul>
+      {data.map(todo => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+> [!NOTE]
+> TanStack Query v5は最新バージョンであり、APIの簡素化やTypeScriptサポートの改善など、大幅な改良が含まれています。

package/template/content/query/zh-hans/guides/mutations.md

@@ -0,0 +1,126 @@
+---
+title: 变更操作
+description: 了解如何使用 TanStack Query 的变更操作创建、更新和删除数据
+---
+
+# 变更操作
+
+与查询不同，变更操作通常用于创建/更新/删除数据或执行服务端副作用。为此，TanStack Query 导出了 `useMutation` Hook。
+
+## 基本变更操作
+
+```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: () => {
+      // 使待办事项列表缓存失效并重新获取
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button
+      onClick={() => mutation.mutate({ title: 'New Todo' })}
+      disabled={mutation.isPending}
+    >
+      {mutation.isPending ? '添加中...' : '添加待办事项'}
+    </button>
+  )
+}
+```
+
+## 变更状态
+
+在任意时刻，变更操作只能处于以下状态之一：
+
+| 状态 | 描述 |
+|---|---|
+| `isIdle` | 变更操作处于空闲或初始/重置状态 |
+| `isPending` | 变更操作正在执行 |
+| `isError` | 变更操作遇到错误 |
+| `isSuccess` | 变更操作成功，数据可用 |
+
+## 乐观更新
+
+乐观更新允许您在服务器确认变更之前更新 UI，提供更流畅的用户体验：
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // 取消正在进行的重新获取，以避免覆盖乐观更新
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+    // 保存之前的值快照
+    const previousTodos = queryClient.getQueryData(['todos'])
+
+    // 乐观地更新为新值
+    queryClient.setQueryData(['todos'], (old: Todo[]) => [
+      ...old,
+      { ...newTodo, id: Date.now() },
+    ])
+
+    // 返回包含快照值的上下文对象
+    return { previousTodos }
+  },
+  onError: (_err, _newTodo, context) => {
+    // 出错时回滚到之前的值
+    queryClient.setQueryData(['todos'], context?.previousTodos)
+  },
+  onSettled: () => {
+    // 无论成功或失败都重新获取
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+> [!NOTE]
+> `onMutate` 处理函数在变更函数之前运行，并接收相同的变量。这是执行乐观更新的最佳位置。
+
+## 重试
+
+默认情况下，TanStack Query 不会重试失败的变更操作。您可以为每个变更操作单独配置：
+
+```tsx
+const mutation = useMutation({
+  mutationFn: addTodo,
+  retry: 3, // 失败的变更操作重试 3 次
+})
+```
+
+## 变更回调
+
+`useMutation` Hook 支持多个回调选项：
+
+```tsx
+useMutation({
+  mutationFn: addTodo,
+  onMutate: (variables) => {
+    // 在变更函数触发之前调用
+    // 接收变更函数将接收的相同变量
+  },
+  onError: (error, variables, context) => {
+    // 变更操作遇到错误时调用
+  },
+  onSuccess: (data, variables, context) => {
+    // 变更操作成功时调用
+  },
+  onSettled: (data, error, variables, context) => {
+    // 无论成功还是失败都会调用
+  },
+})
+```
+
+> [!WARNING]
+> `useMutation` 上的回调会在每个使用它的组件实例中触发。要确保副作用只执行一次，请使用 `mutate` 函数上的回调，或将变更操作提取到共享 Hook 中。