docs-i18n 0.8.0 → 0.8.2

package/template/content/query/zh-hans/quick-start.md

@@ -0,0 +1,108 @@
+---
+title: 快速开始
+description: 几分钟内上手 TanStack Query
+---
+
+# 快速开始
+
+本指南将帮助您尽快上手 TanStack Query。
+
+## 设置 Provider
+
+使用 `QueryClientProvider` 包裹您的应用，并传入一个 `QueryClient` 实例：
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const queryClient = new QueryClient()
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <MyApp />
+    </QueryClientProvider>
+  )
+}
+```
+
+## 您的第一个查询
+
+使用 `useQuery` Hook 来获取数据：
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function Todos() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  if (isLoading) return <span>加载中...</span>
+  if (error) return <span>错误：{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()
+}
+```
+
+## 您的第一个变更操作
+
+使用 `useMutation` 来创建、更新或删除数据：
+
+```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: () => {
+      // 使缓存失效并重新获取
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button onClick={() => mutation.mutate({ title: 'New Todo' })}>
+      添加待办事项
+    </button>
+  )
+}
+```
+
+## 添加开发工具
+
+添加 React Query Devtools 进行调试：
+
+```tsx
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <MyApp />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  )
+}
+```
+
+> [!NOTE]
+> 开发工具在生产构建中会自动排除。

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

@@ -0,0 +1,18 @@
+{
+  "sections": [
+    {
+      "label": "Getting Started",
+      "children": [
+        { "label": "Overview", "to": "overview" },
+        { "label": "Installation", "to": "installation" },
+        { "label": "Quick Start", "to": "quick-start" }
+      ]
+    },
+    {
+      "label": "Guides",
+      "children": [
+        { "label": "Routing Concepts", "to": "guides/routing-concepts" }
+      ]
+    }
+  ]
+}

package/template/content/router/en/guides/routing-concepts.md

@@ -0,0 +1,131 @@
+---
+title: Routing Concepts
+description: Understand the core routing concepts in TanStack Router
+---
+
+# Routing Concepts
+
+TanStack Router is built on a few core concepts that make it powerful and flexible. Understanding these concepts will help you build better applications.
+
+## Route Trees
+
+TanStack Router uses a route tree to define the structure of your application. Routes can be nested to create layouts and hierarchies:
+
+```tsx
+import { createRootRoute, createRoute, createRouter } from '@tanstack/react-router'
+
+const rootRoute = createRootRoute({
+  component: RootLayout,
+})
+
+const indexRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/',
+  component: HomePage,
+})
+
+const aboutRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/about',
+  component: AboutPage,
+})
+
+const routeTree = rootRoute.addChildren([indexRoute, aboutRoute])
+
+const router = createRouter({ routeTree })
+```
+
+## File-Based Routing
+
+For most applications, TanStack Router supports file-based routing through a plugin. Your file structure becomes your route structure:
+
+```
+app/
+  routes/
+    __root.tsx        → Root layout
+    index.tsx         → /
+    about.tsx         → /about
+    posts.tsx         → /posts (layout)
+    posts.index.tsx   → /posts/
+    posts.$postId.tsx → /posts/:postId
+```
+
+> [!NOTE]
+> File-based routing is powered by the `@tanstack/router-plugin` package, which generates the route tree automatically at build time.
+
+## Search Params
+
+TanStack Router treats search params as first-class citizens with full type safety:
+
+```tsx
+const productsRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/products',
+  validateSearch: (search: Record<string, unknown>) => {
+    return {
+      page: Number(search.page) || 1,
+      filter: (search.filter as string) || '',
+      sort: (search.sort as 'asc' | 'desc') || 'asc',
+    }
+  },
+  component: ProductsPage,
+})
+
+function ProductsPage() {
+  const { page, filter, sort } = productsRoute.useSearch()
+
+  return (
+    <div>
+      <p>Page: {page}, Filter: {filter}, Sort: {sort}</p>
+    </div>
+  )
+}
+```
+
+## Data Loading
+
+Routes can define loaders that fetch data before the route renders:
+
+```tsx
+const postRoute = createRoute({
+  getParentRoute: () => postsRoute,
+  path: '$postId',
+  loader: async ({ params }) => {
+    const post = await fetchPost(params.postId)
+    return { post }
+  },
+  component: PostPage,
+})
+
+function PostPage() {
+  const { post } = postRoute.useLoaderData()
+  return <article>{post.title}</article>
+}
+```
+
+| Feature | Description |
+|---|---|
+| Route Trees | Hierarchical route definitions with parent-child relationships |
+| File-Based Routing | Automatic route generation from file system |
+| Search Params | Type-safe URL search parameters with validation |
+| Data Loading | Pre-fetch data before route renders |
+| Pending States | Built-in loading indicators during navigation |
+| Error Boundaries | Per-route error handling |
+
+## Path Params
+
+Dynamic segments in the path are prefixed with `$`:
+
+```tsx
+// Single param
+'/posts/$postId'
+
+// Multiple params
+'/users/$userId/posts/$postId'
+
+// Splat/catch-all
+'/files/$'
+```
+
+> [!WARNING]
+> Unlike some other routers, TanStack Router does not use `:` for dynamic segments. Always use `$` as the prefix.

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

@@ -0,0 +1,57 @@
+---
+title: Installation
+description: How to install TanStack Router in your project
+---
+
+# Installation
+
+## Install the Package
+
+```bash
+npm install @tanstack/react-router
+```
+
+```bash
+pnpm add @tanstack/react-router
+```
+
+```bash
+yarn add @tanstack/react-router
+```
+
+```bash
+bun add @tanstack/react-router
+```
+
+## Vite Plugin (Recommended)
+
+For the best experience with file-based routing and automatic route generation, install the Vite plugin:
+
+```bash
+npm install -D @tanstack/router-plugin
+```
+
+Then add it to your `vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
+
+export default defineConfig({
+  plugins: [TanStackRouterVite(), react()],
+})
+```
+
+## Devtools
+
+Install the devtools for route debugging:
+
+```bash
+npm install @tanstack/router-devtools
+```
+
+## Requirements
+
+- React 18+
+- TypeScript 5.0+ (strongly recommended)

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

@@ -0,0 +1,74 @@
+---
+title: TanStack Router Overview
+description: Type-safe routing for React applications with first-class search param support
+---
+
+# TanStack Router
+
+TanStack Router is a fully type-safe React router with built-in data fetching, stale-while-revalidate caching, and first-class search param APIs.
+
+## Why TanStack Router?
+
+Traditional routers have limited type safety and treat search params as an afterthought. TanStack Router was built from the ground up with type safety and search params as first-class citizens.
+
+## Features
+
+- **100% Type-Safe** — Route paths, params, search params, and loaders are all fully typed
+- **Built-in Search Params** — First-class search param management with validation
+- **Data Loading** — Integrated route loaders with stale-while-revalidate caching
+- **Code Splitting** — Automatic route-based code splitting
+- **Nested Layouts** — Nested routes with shared layouts
+- **Devtools** — Dedicated devtools for debugging routes and cache
+
+## Basic Example
+
+```tsx
+import {
+  createRouter,
+  createRoute,
+  createRootRoute,
+} from '@tanstack/react-router'
+
+const rootRoute = createRootRoute({
+  component: () => (
+    <div>
+      <nav>
+        <Link to="/">Home</Link>
+        <Link to="/about">About</Link>
+      </nav>
+      <Outlet />
+    </div>
+  ),
+})
+
+const indexRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/',
+  component: () => <div>Welcome Home!</div>,
+})
+
+const aboutRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/about',
+  component: () => <div>About</div>,
+})
+
+const routeTree = rootRoute.addChildren([indexRoute, aboutRoute])
+
+const router = createRouter({ routeTree })
+```
+
+## Type-Safe Search Params
+
+```tsx
+const productsRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/products',
+  validateSearch: (search) => ({
+    page: Number(search.page ?? 1),
+    filter: (search.filter as string) ?? '',
+    sort: (search.sort as 'asc' | 'desc') ?? 'asc',
+  }),
+  component: ProductsPage,
+})
+```

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

@@ -0,0 +1,88 @@
+---
+title: Quick Start
+description: Get up and running with TanStack Router in minutes
+---
+
+# Quick Start
+
+## File-Based Routing
+
+The easiest way to get started is with file-based routing. Create your routes directory:
+
+```
+src/
+  routes/
+    __root.tsx
+    index.tsx
+    about.tsx
+    posts/
+      index.tsx
+      $postId.tsx
+```
+
+### Root Route
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+  component: () => (
+    <>
+      <nav>
+        <Link to="/">Home</Link>
+        <Link to="/about">About</Link>
+        <Link to="/posts">Posts</Link>
+      </nav>
+      <Outlet />
+    </>
+  ),
+})
+```
+
+### Index Route
+
+```tsx
+// src/routes/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/')({
+  component: () => <div>Welcome Home!</div>,
+})
+```
+
+### Dynamic Route
+
+```tsx
+// src/routes/posts/$postId.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    return fetchPost(params.postId)
+  },
+  component: PostPage,
+})
+
+function PostPage() {
+  const post = Route.useLoaderData()
+  return <div>{post.title}</div>
+}
+```
+
+## Data Loading
+
+TanStack Router supports route-level data loading with caching:
+
+```tsx
+export const Route = createFileRoute('/posts')({
+  loader: async () => {
+    const posts = await fetch('/api/posts').then((r) => r.json())
+    return { posts }
+  },
+  component: PostsPage,
+})
+```
+
+> [!NOTE]
+> Route loaders run in parallel for nested routes, ensuring the fastest possible data loading.

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

@@ -0,0 +1,57 @@
+---
+title: インストール
+description: プロジェクトに TanStack Router をインストールする方法
+---
+
+# インストール
+
+## パッケージのインストール
+
+```bash
+npm install @tanstack/react-router
+```
+
+```bash
+pnpm add @tanstack/react-router
+```
+
+```bash
+yarn add @tanstack/react-router
+```
+
+```bash
+bun add @tanstack/react-router
+```
+
+## Vite プラグイン（推奨）
+
+ファイルベースルーティングと自動ルート生成で最高の体験を得るために、Vite プラグインをインストールしてください：
+
+```bash
+npm install -D @tanstack/router-plugin
+```
+
+`vite.config.ts` に追加します：
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
+
+export default defineConfig({
+  plugins: [TanStackRouterVite(), react()],
+})
+```
+
+## Devtools
+
+ルートデバッグ用の devtools をインストールします：
+
+```bash
+npm install @tanstack/router-devtools
+```
+
+## 必要要件
+
+- React 18+
+- TypeScript 5.0+（強く推奨）

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

@@ -0,0 +1,78 @@
+---
+title: TanStack Router 概要
+description: Reactアプリケーション向けの型安全なルーティングライブラリ
+---
+
+# TanStack Router
+
+TanStack Routerは、Reactアプリケーション向けに設計された完全型安全なルーティングライブラリです。ナビゲーションからサーチパラメータまで、エンドツーエンドの型安全性を提供します。
+
+## なぜTanStack Routerを選ぶのか？
+
+従来のReactルーティングライブラリは型安全性の面で不十分でした。ルートパスは文字列、パラメータは`any`型、サーチパラメータはまったく検証されません。TanStack Routerはこれらの問題を根本から解決します。
+
+## 主な特徴
+
+- **100% 型安全** — リンク、ナビゲーション、パラメータ、サーチパラメータすべてが完全に型チェックされる
+- **ファーストクラスのサーチパラメータ** — URLサーチパラメータが検証され型付けされる
+- **組み込みデータローディング** — ルートレベルのデータプリフェッチ
+- **ファイルベースルーティング** — ファイルシステムから型安全なルートツリーを自動生成
+- **ネストされたレイアウト** — ルートのネストで共有レイアウトを作成
+- **コード分割** — ルートごとのコード分割を標準サポート
+
+## クイック例
+
+```tsx
+import {
+  createRootRoute,
+  createRoute,
+  createRouter,
+  Link,
+  Outlet,
+} from '@tanstack/react-router'
+
+const rootRoute = createRootRoute({
+  component: () => (
+    <div>
+      <nav>
+        <Link to="/">ホーム</Link>
+        <Link to="/about">アバウト</Link>
+      </nav>
+      <Outlet />
+    </div>
+  ),
+})
+
+const indexRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/',
+  component: () => <h1>ホームページへようこそ</h1>,
+})
+
+const aboutRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/about',
+  component: () => <h1>私たちについて</h1>,
+})
+
+const routeTree = rootRoute.addChildren([indexRoute, aboutRoute])
+const router = createRouter({ routeTree })
+```
+
+## TanStack Queryとの連携
+
+TanStack RouterはTanStack Queryと相性が抜群です。ルートの`loader`でQueryを使用してデータをプリフェッチできます：
+
+```tsx
+const userRoute = createRoute({
+  path: '/users/$userId',
+  loader: ({ params, context }) =>
+    context.queryClient.ensureQueryData({
+      queryKey: ['user', params.userId],
+      queryFn: () => fetchUser(params.userId),
+    }),
+})
+```
+
+> [!NOTE]
+> TanStack Routerは単独で使用することも、TanStack Startと組み合わせてフルスタックフレームワークとして使用することもできます。