docs-i18n 0.8.1 → 0.8.3

package/template/content/blog/en/state-management-2024.md

@@ -0,0 +1,143 @@
+---
+title: "The State of State Management in 2024"
+published: "2024-08-20"
+excerpt: "Server state vs client state, signals vs hooks, atoms vs stores — a practical guide to choosing the right state management approach for your React application in 2024."
+authors:
+  - "docs-i18n Team"
+---
+
+State management in React has evolved dramatically. The days of putting everything in Redux are over. In 2024, the ecosystem has matured into a set of specialized tools, each solving a specific problem well.
+
+## The Two Kinds of State
+
+The most important mental model shift in modern state management is the distinction between **server state** and **client state**.
+
+**Server state** is data that:
+- Lives on the server / database
+- Is fetched asynchronously
+- Can become stale
+- Is shared across users
+
+**Client state** is data that:
+- Exists only in the browser
+- Is synchronous
+- Is local to the user's session
+- Examples: UI toggles, form inputs, selected tabs
+
+```tsx
+// Server state — use TanStack Query
+const { data: todos } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+// Client state — use React state or a small store
+const [isOpen, setIsOpen] = useState(false)
+const [selectedTab, setSelectedTab] = useState('all')
+```
+
+> [!NOTE]
+> If you separate server state from client state, you will find that most applications need very little client state management. TanStack Query (or a similar library) handles the majority of your state.
+
+## Server State Libraries
+
+### TanStack Query
+
+The most feature-rich option for server state management. Provides caching, background refetching, mutations with optimistic updates, pagination, infinite scroll, and excellent devtools.
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+
+function TodoApp() {
+  const queryClient = useQueryClient()
+  const todos = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+
+  const addTodo = useMutation({
+    mutationFn: createTodo,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+  })
+
+  return (
+    <div>
+      {todos.data?.map((todo) => <Todo key={todo.id} todo={todo} />)}
+      <button onClick={() => addTodo.mutate({ title: 'New' })}>Add</button>
+    </div>
+  )
+}
+```
+
+### SWR
+
+A lighter alternative focused on data fetching. Smaller bundle, simpler API, fewer features.
+
+### tRPC
+
+End-to-end type-safe APIs. Built on top of TanStack Query, so you get all its caching benefits plus type-safe API calls.
+
+## Client State Libraries
+
+### React `useState` / `useReducer`
+
+For most client state, built-in React state is sufficient. Do not reach for a library until you have a clear need.
+
+### Zustand
+
+When you need global client state (theme, user preferences, complex UI state), Zustand provides a minimal, hook-based API:
+
+```tsx
+import { create } from 'zustand'
+
+const useStore = create((set) => ({
+  bears: 0,
+  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
+}))
+
+function BearCounter() {
+  const bears = useStore((state) => state.bears)
+  return <h1>{bears} bears</h1>
+}
+```
+
+### Jotai
+
+Atomic state management inspired by Recoil. Great for fine-grained reactivity:
+
+```tsx
+import { atom, useAtom } from 'jotai'
+
+const countAtom = atom(0)
+const doubledAtom = atom((get) => get(countAtom) * 2)
+
+function Counter() {
+  const [count, setCount] = useAtom(countAtom)
+  const [doubled] = useAtom(doubledAtom)
+  return <div>{count} (doubled: {doubled})</div>
+}
+```
+
+## Decision Framework
+
+| Need | Recommended Tool |
+|---|---|
+| Fetching / caching server data | TanStack Query or SWR |
+| Local component state | `useState` / `useReducer` |
+| Shared UI state (theme, modals) | Zustand or Jotai |
+| Complex form state | TanStack Form |
+| URL state (search params, pagination) | TanStack Router |
+| End-to-end type-safe API | tRPC + TanStack Query |
+
+## The Pattern
+
+The most successful React applications in 2024 follow this pattern:
+
+1. **TanStack Query** for all server state
+2. **TanStack Router** for URL-driven state
+3. **React `useState`** for local UI state
+4. **Zustand or Jotai** (only if needed) for global client state
+
+> [!WARNING]
+> Avoid putting server data in a global client state store (Redux, Zustand, etc.). This leads to stale data, duplicated caching logic, and unnecessary complexity. Use TanStack Query for server state.
+
+## Conclusion
+
+State management in 2024 is not about choosing one library to rule them all. It is about using the right tool for the right kind of state. Start simple, add complexity only when needed, and let specialized libraries handle what they do best.

package/template/content/blog/en/tanstack-router-1.0.md

@@ -0,0 +1,121 @@
+---
+title: "TanStack Router 1.0: Type-Safe Routing for React"
+published: "2024-03-15"
+excerpt: "TanStack Router 1.0 is stable! With 100% type-safe navigation, built-in search params, and first-class data loading, it is the most type-safe router for React."
+authors:
+  - "Tanner Linsley"
+---
+
+After years of development and months of beta testing, we are proud to announce TanStack Router 1.0 is stable and production-ready.
+
+## Why Another Router?
+
+React Router has served the community well for years. But as TypeScript adoption has grown, developers have increasingly wanted a router that provides end-to-end type safety. TanStack Router was built from the ground up with TypeScript as a first-class citizen.
+
+## Key Features
+
+### 100% Type-Safe Navigation
+
+Every `Link`, `navigate`, and `redirect` in TanStack Router is fully type-checked:
+
+```tsx
+// TypeScript will error if:
+// - The route does not exist
+// - Required params are missing
+// - Search params do not match the schema
+<Link
+  to="/users/$userId/posts/$postId"
+  params={{ userId: '1', postId: '42' }}
+  search={{ sort: 'date' }}
+/>
+
+// This would be a type error:
+<Link
+  to="/users/$userId/posts/$postId"
+  params={{ userId: '1' }} // Error: missing postId
+/>
+```
+
+### First-Class Search Params
+
+URL search parameters are validated and typed:
+
+```tsx
+const productsRoute = createRoute({
+  path: '/products',
+  validateSearch: z.object({
+    page: z.number().default(1),
+    category: z.string().optional(),
+    sort: z.enum(['price', 'name', 'rating']).default('name'),
+  }),
+})
+
+// In your component:
+const { page, category, sort } = productsRoute.useSearch()
+// ^ All fully typed!
+```
+
+### Built-In Data Loading
+
+No need for separate data fetching libraries for route-level data:
+
+```tsx
+const userRoute = createRoute({
+  path: '/users/$userId',
+  loader: async ({ params, context }) => {
+    return context.queryClient.ensureQueryData({
+      queryKey: ['user', params.userId],
+      queryFn: () => fetchUser(params.userId),
+    })
+  },
+})
+```
+
+### File-Based Routing
+
+For larger applications, file-based routing generates the type-safe route tree automatically:
+
+```
+routes/
+  __root.tsx
+  index.tsx
+  about.tsx
+  users.tsx
+  users.$userId.tsx
+  users.$userId.posts.tsx
+  users.$userId.posts.$postId.tsx
+```
+
+The router plugin generates a `routeTree.gen.ts` file with complete type information.
+
+## Migration from React Router
+
+We understand that migrating routers is a significant effort. We have published a detailed [migration guide](/en/router/docs/guides/migration-from-react-router) and built a codemod to help:
+
+```bash
+npx @tanstack/router-codemod from-react-router ./src
+```
+
+## Performance
+
+TanStack Router is designed for performance:
+
+- **Route-level code splitting** works out of the box with file-based routing
+- **Prefetching** on link hover ensures instant navigations
+- **Parallel data loading** fetches data for all matched routes simultaneously
+- **Stale-while-revalidate** keeps the UI responsive during refetches
+
+> [!NOTE]
+> TanStack Router pairs beautifully with TanStack Query. Use the router for route-level data loading and Query for component-level data fetching.
+
+## Get Started
+
+Install TanStack Router today:
+
+```bash
+npm install @tanstack/react-router @tanstack/router-plugin
+```
+
+Read the [quick start guide](/en/router/docs/quick-start) to build your first type-safe route.
+
+Thank you to everyone who contributed during the alpha and beta phases. Your feedback shaped this release into something we are truly proud of.

package/template/content/blog/ja/announcing-query-v5.md

@@ -0,0 +1,110 @@
+---
+title: "TanStack Query v5 のリリースを発表"
+published: "2024-10-01"
+excerpt: "TanStack Query v5 が登場しました。シンプルになった API、強化された TypeScript サポート、改善された devtools、そしてより小さなバンドルサイズを実現しています。"
+authors:
+  - "Tanner Linsley"
+  - "Dominik Dorfmeister"
+---
+
+TanStack Query v5 のリリースを発表できることを大変嬉しく思います！このリリースはコミュニティの数ヶ月にわたる作業の成果であり、全体的に大幅な改善をもたらします。
+
+## 新機能
+
+### シンプルになった API
+
+v5 で最も目に見える変更はシンプルになった API です。オブジェクト構文のオーバーロードを廃止し、すべてのフックで単一の一貫したオブジェクト構文を採用しました：
+
+```tsx
+// v4 — 複数のオーバーロード
+useQuery(['todos'], fetchTodos)
+useQuery(['todos'], fetchTodos, { staleTime: 5000 })
+useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+
+// v5 — 単一の一貫した API
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 5000,
+})
+```
+
+これにより API の学習が容易になり、TypeScript の推論も向上しました。
+
+### TypeScript サポートの強化
+
+v5 には TypeScript の大幅な改善が含まれています：
+
+- **厳密なクエリキーの型付け** — クエリキーが全体を通じて厳密に型付けされるようになりました
+- **推論される戻り値の型** — `useQuery` が `queryFn` から戻り値の型を正しく推論します
+- **型安全なエラーハンドリング** — 新しい `Error` ジェネリックパラメータによりエラーが適切に型付けされます
+
+```tsx
+// エラーの型が推論され、型安全になります
+const { data, error } = useQuery({
+  queryKey: ['user', userId],
+  queryFn: async () => {
+    const res = await fetch(`/api/users/${userId}`)
+    if (!res.ok) throw new ApiError(res.status, await res.text())
+    return res.json() as Promise<User>
+  },
+})
+
+// error は ApiError | null として型付けされます
+if (error) {
+  console.log(error.status) // TypeScript はこれが存在することを知っています
+}
+```
+
+### 新しい Devtools
+
+Devtools は新しいデザイン、パフォーマンスの向上、新機能で完全に書き直されました：
+
+- **クエリタイムライン** — 時間経過によるクエリフェッチの可視化
+- **ミューテーションインスペクター** — ミューテーションの状態と変数を検査
+- **キャッシュエクスプローラー** — クエリキャッシュ全体をブラウズ
+- **オンライン/オフライン切替** — オフライン動作のテスト
+
+### バンドルサイズの削減
+
+ツリーシェイキングの改善と非推奨 API の削除により、コアバンドルサイズを約 20% 削減しました。
+
+| パッケージ | v4 | v5 | 変化 |
+|---|---|---|---|
+| `@tanstack/react-query` | 12.4 KB | 9.8 KB | -21% |
+| `@tanstack/query-core` | 10.1 KB | 8.2 KB | -19% |
+
+## 破壊的変更
+
+> [!WARNING]
+> v5 にはいくつかの破壊的変更が含まれています。アップグレード前に完全な[マイグレーションガイド](/ja/query/docs/guides/migration-v5)をご確認ください。
+
+主な破壊的変更：
+
+1. **オーバーロードシグネチャの廃止** — すべてのフックがオブジェクトのみの構文を使用
+2. **`cacheTime` を `gcTime` にリネーム** — その目的（ガベージコレクション時間）をより適切に反映
+3. **`status: 'loading'` を `status: 'pending'` にリネーム** — Promise の用語に合わせて
+4. **`keepPreviousData` の廃止** — `placeholderData: keepPreviousData`（query core からインポート）に置き換え
+5. **TypeScript の最低バージョンが 4.7 に**
+
+## マイグレーション
+
+マイグレーションの大部分を自動化する codemod を用意しています：
+
+```bash
+npx @tanstack/query-codemod v5 ./src
+```
+
+これにより最も一般的な変換が自動的に行われます。変更内容を確認し、十分にテストしてください。
+
+## ありがとうございます
+
+このリリースを可能にしてくれた 100 人以上のコントリビューターに感謝します。TanStack Query v5 は、素晴らしいオープンソースコミュニティなしには実現できませんでした。
+
+今すぐ v5 を始めましょう：
+
+```bash
+npm install @tanstack/react-query@latest
+```
+
+Happy querying!

package/template/content/blog/ja/hello-world.md

@@ -0,0 +1,26 @@
+---
+title: "Hello World：docs-i18n ブログの紹介"
+published: "2024-01-15"
+excerpt: "docs-i18n ブログへようこそ！プロジェクトの更新情報、チュートリアル、ドキュメント国際化のベストプラクティスを共有します。"
+authors:
+  - "docs-i18n Team"
+---
+
+docs-i18n ブログへようこそ！ここでは、プロジェクトの更新情報、チュートリアル、ドキュメント国際化のベストプラクティスを共有します。
+
+## docs-i18n とは？
+
+docs-i18n は、多言語ドキュメントサイトを簡単に維持できるようにする汎用ドキュメント翻訳エンジンです。以下を提供します：
+
+- **ファイルシステムベースのコンテンツ読み込み**（i18n フォールバック付き）
+- **Markdown レンダリング**（シンタックスハイライトとフレームワーク対応コンテンツ）
+- **管理インターフェース**（翻訳の管理用）
+- **CLI ツール**（翻訳ワークフローの自動化用）
+
+## はじめに
+
+[入門ガイド](/ja/getting-started)をご覧ください。docs-i18n のプロジェクトへの導入方法を学べます。
+
+## 今後にご期待ください
+
+今後のリリースでは、エキサイティングな新機能を予定しています。最新の情報はこのブログでお届けします！

package/template/content/blog/zh-hans/announcing-query-v5.md

@@ -0,0 +1,93 @@
+---
+title: "TanStack Query v5 正式发布"
+published: "2024-10-01"
+excerpt: "TanStack Query v5 带来了简化的 API、更好的 TypeScript 支持、改进的开发工具和更小的包体积。以下是你需要了解的一切。"
+authors:
+  - "Tanner Linsley"
+  - "Dominik Dorfmeister"
+---
+
+我们非常高兴地宣布 TanStack Query v5 正式发布！这个版本凝聚了社区数月的努力，在各方面都带来了重大改进。
+
+## 新特性
+
+### 简化的 API
+
+v5 最直观的变化是简化的 API。我们移除了多种函数签名重载，统一使用单一的对象语法：
+
+```tsx
+// v4 — 多种重载方式
+useQuery(['todos'], fetchTodos)
+useQuery(['todos'], fetchTodos, { staleTime: 5000 })
+useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+
+// v5 — 统一的对象语法
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 5000,
+})
+```
+
+这使得 API 更容易学习，并提供更好的 TypeScript 类型推断。
+
+### 更好的 TypeScript 支持
+
+v5 包含重大的 TypeScript 改进：
+
+- **严格的查询键类型** — 查询键在整个流程中都经过严格类型检查
+- **推断的返回类型** — `useQuery` 能从 `queryFn` 正确推断返回类型
+- **类型安全的错误处理** — 通过新的 `Error` 泛型参数实现类型安全的错误处理
+
+```tsx
+const { data, error } = useQuery({
+  queryKey: ['user', userId],
+  queryFn: async () => {
+    const res = await fetch(`/api/users/${userId}`)
+    if (!res.ok) throw new ApiError(res.status, await res.text())
+    return res.json() as Promise<User>
+  },
+})
+
+// error 的类型为 ApiError | null
+if (error) {
+  console.log(error.status) // TypeScript 知道这个属性存在
+}
+```
+
+### 更小的包体积
+
+通过 tree-shaking 优化和移除废弃的 API，我们将核心包体积减少了约 20%。
+
+| 包 | v4 | v5 | 变化 |
+|---|---|---|---|
+| `@tanstack/react-query` | 12.4 KB | 9.8 KB | -21% |
+| `@tanstack/query-core` | 10.1 KB | 8.2 KB | -19% |
+
+## 破坏性变更
+
+> [!WARNING]
+> v5 包含多项破坏性变更。请在升级前仔细阅读完整的迁移指南。
+
+主要破坏性变更：
+
+1. **移除了重载签名** — 所有 hook 现在仅使用对象语法
+2. **`cacheTime` 重命名为 `gcTime`** — 更好地反映其用途（垃圾回收时间）
+3. **`status: 'loading'` 重命名为 `status: 'pending'`** — 与 Promise 术语保持一致
+4. **最低 TypeScript 版本要求为 4.7**
+
+## 迁移
+
+我们提供了 codemod 工具来自动化大部分迁移工作：
+
+```bash
+npx @tanstack/query-codemod v5 ./src
+```
+
+立即开始使用 v5：
+
+```bash
+npm install @tanstack/react-query@latest
+```
+
+感谢所有让这个版本成为可能的 100 多位贡献者！

package/template/content/blog/zh-hans/hello-world.md

@@ -0,0 +1,26 @@
+---
+title: "你好世界：docs-i18n 博客上线"
+published: "2024-01-15"
+excerpt: "欢迎来到 docs-i18n 博客！我们将分享更新、教程和文档国际化的最佳实践。"
+authors:
+  - "docs-i18n Team"
+---
+
+欢迎来到 docs-i18n 博客！这里我们将分享项目更新、教程和文档国际化的最佳实践。
+
+## 什么是 docs-i18n？
+
+docs-i18n 是一个通用的文档翻译引擎，可以轻松维护多语言文档站点。它提供：
+
+- **基于文件系统的内容加载**，支持 i18n 回退
+- **Markdown 渲染**，支持语法高亮和框架感知内容
+- **管理界面**，用于管理翻译
+- **CLI 工具**，用于自动化翻译工作流
+
+## 开始使用
+
+查看我们的[入门指南](/zh-hans/getting-started)来了解如何为你的项目设置 docs-i18n。
+
+## 敬请期待
+
+我们计划在即将发布的版本中推出令人兴奋的新功能。关注这个博客获取最新更新！

package/template/content/docs-i18n/docs.config.json

@@ -0,0 +1,25 @@
+{
+  "sections": [
+    {
+      "label": "Getting Started",
+      "children": [
+        { "label": "Introduction", "to": "getting-started" }
+      ]
+    },
+    {
+      "label": "Usage",
+      "children": [
+        { "label": "CLI Commands", "to": "cli" },
+        { "label": "Configuration", "to": "configuration" },
+        { "label": "Admin Dashboard", "to": "admin" }
+      ]
+    },
+    {
+      "label": "Advanced",
+      "children": [
+        { "label": "Architecture", "to": "architecture" },
+        { "label": "Deployment", "to": "deployment" }
+      ]
+    }
+  ]
+}