docs-i18n 0.8.0 → 0.8.2

package/template/content/router/zh-hans/guides/routing-concepts.md

@@ -0,0 +1,131 @@
+---
+title: 路由概念
+description: 了解 TanStack Router 的核心路由概念
+---
+
+# 路由概念
+
+TanStack Router 建立在几个核心概念之上，使其功能强大且灵活。理解这些概念将帮助您构建更好的应用。
+
+## 路由树
+
+TanStack Router 使用路由树来定义应用的结构。路由可以嵌套以创建布局和层级结构：
+
+```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 })
+```
+
+## 基于文件的路由
+
+对于大多数应用，TanStack Router 通过插件支持基于文件的路由。您的文件结构即是路由结构：
+
+```
+app/
+  routes/
+    __root.tsx        → 根布局
+    index.tsx         → /
+    about.tsx         → /about
+    posts.tsx         → /posts（布局）
+    posts.index.tsx   → /posts/
+    posts.$postId.tsx → /posts/:postId
+```
+
+> [!NOTE]
+> 基于文件的路由由 `@tanstack/router-plugin` 包驱动，它在构建时自动生成路由树。
+
+## 搜索参数
+
+TanStack Router 将搜索参数视为一等公民，提供完整的类型安全：
+
+```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}，筛选：{filter}，排序：{sort}</p>
+    </div>
+  )
+}
+```
+
+## 数据加载
+
+路由可以定义在渲染前获取数据的加载器：
+
+```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>
+}
+```
+
+| 功能 | 描述 |
+|---|---|
+| 路由树 | 具有父子关系的层级路由定义 |
+| 基于文件的路由 | 从文件系统自动生成路由 |
+| 搜索参数 | 带验证的类型安全 URL 搜索参数 |
+| 数据加载 | 在路由渲染前预取数据 |
+| 等待状态 | 导航期间的内置加载指示器 |
+| 错误边界 | 按路由的错误处理 |
+
+## 路径参数
+
+路径中的动态段以 `$` 为前缀：
+
+```tsx
+// 单个参数
+'/posts/$postId'
+
+// 多个参数
+'/users/$userId/posts/$postId'
+
+// 通配符/全匹配
+'/files/$'
+```
+
+> [!WARNING]
+> 与其他路由器不同，TanStack Router 不使用 `:` 作为动态段前缀。始终使用 `$` 作为前缀。

package/template/content/router/zh-hans/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()],
+})
+```
+
+## 开发工具
+
+安装开发工具用于路由调试：
+
+```bash
+npm install @tanstack/router-devtools
+```
+
+## 环境要求
+
+- React 18+
+- TypeScript 5.0+（强烈推荐）

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

@@ -0,0 +1,81 @@
+---
+title: TanStack Router 概述
+description: 为 React 应用打造的类型安全路由库
+---
+
+# TanStack Router
+
+TanStack Router 是一个为 React 应用设计的全类型安全路由库。它将路由提升为一等公民，提供从导航到搜索参数的端到端类型安全。
+
+## 为什么选择 TanStack Router？
+
+传统的 React 路由库在类型安全方面存在不足。路由路径是字符串，参数是 `any` 类型，搜索参数完全未经验证。TanStack Router 从根本上解决了这些问题。
+
+## 核心特性
+
+- **100% 类型安全** — 链接、导航、参数和搜索参数都经过完整的类型检查
+- **一等搜索参数** — URL 搜索参数经过验证和类型化，如同路径参数一样
+- **内置数据加载** — 路由级别的数据预取，支持 stale-while-revalidate
+- **文件路由** — 通过文件系统结构自动生成类型安全的路由树
+- **嵌套布局** — 路由可嵌套以创建共享布局
+- **代码分割** — 开箱即用的按路由代码分割
+
+## 快速示例
+
+```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 结合使用以获得完整的全栈框架体验。

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

@@ -0,0 +1,88 @@
+---
+title: 快速开始
+description: 几分钟内上手 TanStack Router
+---
+
+# 快速开始
+
+## 基于文件的路由
+
+最简单的入门方式是使用基于文件的路由。创建您的路由目录：
+
+```
+src/
+  routes/
+    __root.tsx
+    index.tsx
+    about.tsx
+    posts/
+      index.tsx
+      $postId.tsx
+```
+
+### 根路由
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+  component: () => (
+    <>
+      <nav>
+        <Link to="/">首页</Link>
+        <Link to="/about">关于</Link>
+        <Link to="/posts">文章</Link>
+      </nav>
+      <Outlet />
+    </>
+  ),
+})
+```
+
+### 索引路由
+
+```tsx
+// src/routes/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/')({
+  component: () => <div>欢迎回来！</div>,
+})
+```
+
+### 动态路由
+
+```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>
+}
+```
+
+## 数据加载
+
+TanStack Router 支持带缓存的路由级数据加载：
+
+```tsx
+export const Route = createFileRoute('/posts')({
+  loader: async () => {
+    const posts = await fetch('/api/posts').then((r) => r.json())
+    return { posts }
+  },
+  component: PostsPage,
+})
+```
+
+> [!NOTE]
+> 嵌套路由的路由加载器会并行运行，确保最快的数据加载速度。

package/template/content/table/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": "Column Definitions", "to": "guides/column-definitions" }
+      ]
+    }
+  ]
+}

package/template/content/table/en/guides/column-definitions.md

@@ -0,0 +1,135 @@
+---
+title: Column Definitions
+description: Learn how to define and configure columns in TanStack Table
+---
+
+# Column Definitions
+
+Column definitions are the single most important part of building a table. They are responsible for defining the data model, how data is displayed, and what features each column supports.
+
+## Column Definition Types
+
+TanStack Table supports three types of column definitions:
+
+| Type | Purpose | Has data accessor? |
+|---|---|---|
+| **Accessor Columns** | Display data from your data model | Yes |
+| **Display Columns** | Render arbitrary UI (e.g., action buttons) | No |
+| **Group Columns** | Group other columns under a shared header | No |
+
+## Accessor Columns
+
+Accessor columns are the most common type. They map directly to a field in your data:
+
+```tsx
+import { createColumnHelper } from '@tanstack/react-table'
+
+type Person = {
+  firstName: string
+  lastName: string
+  age: number
+  email: string
+}
+
+const columnHelper = createColumnHelper<Person>()
+
+const columns = [
+  columnHelper.accessor('firstName', {
+    header: 'First Name',
+    cell: (info) => info.getValue(),
+  }),
+  columnHelper.accessor('lastName', {
+    header: 'Last Name',
+  }),
+  columnHelper.accessor('age', {
+    header: 'Age',
+    cell: (info) => <span className="font-mono">{info.getValue()}</span>,
+  }),
+  columnHelper.accessor('email', {
+    header: 'Email',
+    cell: (info) => (
+      <a href={`mailto:${info.getValue()}`} className="text-blue-600 underline">
+        {info.getValue()}
+      </a>
+    ),
+  }),
+]
+```
+
+## Display Columns
+
+Display columns do not have a data accessor and are useful for rendering UI elements like action buttons or row selection checkboxes:
+
+```tsx
+const columns = [
+  columnHelper.display({
+    id: 'select',
+    header: ({ table }) => (
+      <input
+        type="checkbox"
+        checked={table.getIsAllRowsSelected()}
+        onChange={table.getToggleAllRowsSelectedHandler()}
+      />
+    ),
+    cell: ({ row }) => (
+      <input
+        type="checkbox"
+        checked={row.getIsSelected()}
+        onChange={row.getToggleSelectedHandler()}
+      />
+    ),
+  }),
+  // ... accessor columns
+  columnHelper.display({
+    id: 'actions',
+    header: 'Actions',
+    cell: ({ row }) => (
+      <button onClick={() => handleEdit(row.original)}>Edit</button>
+    ),
+  }),
+]
+```
+
+## Column Sizing
+
+You can control column widths through the column definition:
+
+```tsx
+columnHelper.accessor('firstName', {
+  header: 'First Name',
+  size: 200,    // default column size
+  minSize: 100, // minimum column size
+  maxSize: 300, // maximum column size
+})
+```
+
+> [!NOTE]
+> Column sizes are specified in pixels. The table will attempt to respect these sizes but may adjust them based on available space and other column constraints.
+
+## Header Groups
+
+Group columns allow you to create multi-level headers:
+
+```tsx
+const columns = [
+  columnHelper.group({
+    id: 'name',
+    header: 'Name',
+    columns: [
+      columnHelper.accessor('firstName', { header: 'First' }),
+      columnHelper.accessor('lastName', { header: 'Last' }),
+    ],
+  }),
+  columnHelper.group({
+    id: 'info',
+    header: 'Info',
+    columns: [
+      columnHelper.accessor('age', { header: 'Age' }),
+      columnHelper.accessor('email', { header: 'Email' }),
+    ],
+  }),
+]
+```
+
+> [!WARNING]
+> When using group columns, make sure each group has a unique `id`. The `id` is required because group columns do not have an accessor to derive an ID from.

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

@@ -0,0 +1,56 @@
+---
+title: Installation
+description: How to install TanStack Table in your project
+---
+
+# Installation
+
+## React
+
+```bash
+npm install @tanstack/react-table
+```
+
+```bash
+pnpm add @tanstack/react-table
+```
+
+```bash
+yarn add @tanstack/react-table
+```
+
+```bash
+bun add @tanstack/react-table
+```
+
+## Vue
+
+```bash
+npm install @tanstack/vue-table
+```
+
+## Solid
+
+```bash
+npm install @tanstack/solid-table
+```
+
+## Svelte
+
+```bash
+npm install @tanstack/svelte-table
+```
+
+## Requirements
+
+- TypeScript 4.7+ (recommended)
+- React 18+ / Vue 3+ / Solid 1.6+ / Svelte 4+
+
+## Adapter Pattern
+
+TanStack Table uses an adapter pattern. The core logic lives in `@tanstack/table-core`, while framework-specific packages provide thin wrappers:
+
+```ts
+// The core is included automatically — you don't need to install it separately
+import { getCoreRowModel } from '@tanstack/react-table'
+```

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

@@ -0,0 +1,79 @@
+---
+title: TanStack Table Overview
+description: Headless UI for building powerful tables and datagrids
+---
+
+# TanStack Table
+
+TanStack Table is a headless UI library for building powerful tables and datagrids for TS/JS, React, Vue, Solid, and Svelte.
+
+## What is "Headless" UI?
+
+Headless UI is a term for libraries and utilities that provide the logic, state, processing, and API for UI elements and interactions, but do not provide markup, styles, or pre-built implementations.
+
+## Features
+
+- **Framework Agnostic** — Core logic works with React, Vue, Solid, Svelte, and vanilla JS
+- **Sorting** — Multi-column sorting with customizable sort functions
+- **Filtering** — Column and global filtering with custom filter functions
+- **Pagination** — Client-side and server-side pagination
+- **Row Selection** — Single and multi-row selection
+- **Column Ordering & Pinning** — Reorder and pin columns
+- **Column Sizing** — Resizable columns
+- **Virtualization** — Virtual scrolling for large datasets (via TanStack Virtual)
+- **Grouping & Aggregation** — Group rows and aggregate data
+
+## Basic Example
+
+```tsx
+import { createColumnHelper, useReactTable, getCoreRowModel } from '@tanstack/react-table'
+
+type Person = {
+  firstName: string
+  lastName: string
+  age: number
+}
+
+const columnHelper = createColumnHelper<Person>()
+
+const columns = [
+  columnHelper.accessor('firstName', { header: 'First Name' }),
+  columnHelper.accessor('lastName', { header: 'Last Name' }),
+  columnHelper.accessor('age', { header: 'Age' }),
+]
+
+function MyTable({ data }: { data: Person[] }) {
+  const table = useReactTable({
+    data,
+    columns,
+    getCoreRowModel: getCoreRowModel(),
+  })
+
+  return (
+    <table>
+      <thead>
+        {table.getHeaderGroups().map((headerGroup) => (
+          <tr key={headerGroup.id}>
+            {headerGroup.headers.map((header) => (
+              <th key={header.id}>
+                {flexRender(header.column.columnDef.header, header.getContext())}
+              </th>
+            ))}
+          </tr>
+        ))}
+      </thead>
+      <tbody>
+        {table.getRowModel().rows.map((row) => (
+          <tr key={row.id}>
+            {row.getVisibleCells().map((cell) => (
+              <td key={cell.id}>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  )
+}
+```