docs-i18n 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docs-i18n",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Universal documentation translation engine — parse, translate, cache, assemble, manage.",
   "type": "module",
   "bin": {

package/template/app/utils/content-loader.ts

@@ -82,7 +82,11 @@ export function createFsLoader(
     const baseDirs = [
       resolve(projectRoot, 'content', project, version, lang),
       resolve(projectRoot, 'content', project, lang),
+      resolve(projectRoot, 'content', version, lang),
       resolve(projectRoot, 'content', lang),
+      // Flat structure (no lang subdir): content/{version}/ directly
+      resolve(projectRoot, 'content', project, version),
+      resolve(projectRoot, 'content', version),
     ]
 
     if (!urlMapper) {

package/template/app/utils/docs.server.ts

@@ -108,7 +108,11 @@ function loadFilesystemSidebar(
   const candidates = [
     resolve(root, 'content', project, version, 'en'),
     resolve(root, 'content', project, 'en'),
+    resolve(root, 'content', version, 'en'),
     resolve(root, 'content', 'en'),
+    // Flat structure (no lang subdir)
+    resolve(root, 'content', project, version),
+    resolve(root, 'content', version),
   ]
   for (const dir of candidates) {
     if (existsSync(dir) && statSync(dir).isDirectory()) {
@@ -130,7 +134,10 @@ function autoScanDocs(
   const candidates = [
     resolve(root, 'content', project, version, 'en'),
     resolve(root, 'content', project, 'en'),
+    resolve(root, 'content', version, 'en'),
     resolve(root, 'content', 'en'),
+    resolve(root, 'content', project, version),
+    resolve(root, 'content', version),
   ]
 
   for (const dir of candidates) {

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

@@ -0,0 +1,110 @@
+---
+title: "Announcing TanStack Query v5"
+published: "2024-10-01"
+excerpt: "TanStack Query v5 is here with a simplified API, better TypeScript support, improved devtools, and a smaller bundle size. Here is everything you need to know."
+authors:
+  - "Tanner Linsley"
+  - "Dominik Dorfmeister"
+---
+
+We are thrilled to announce the release of TanStack Query v5! This release represents months of work from the community and brings significant improvements across the board.
+
+## What's New
+
+### Simplified API
+
+The most visible change in v5 is the simplified API. We have removed the object syntax overloads in favor of a single, consistent object syntax for all hooks:
+
+```tsx
+// v4 — multiple overloads
+useQuery(['todos'], fetchTodos)
+useQuery(['todos'], fetchTodos, { staleTime: 5000 })
+useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+
+// v5 — single consistent API
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 5000,
+})
+```
+
+This makes the API easier to learn and provides better TypeScript inference.
+
+### Better TypeScript Support
+
+v5 includes major TypeScript improvements:
+
+- **Strict query key typing** — query keys are now strictly typed throughout
+- **Inferred return types** — `useQuery` correctly infers the return type from `queryFn`
+- **Type-safe error handling** — errors are properly typed with the new `Error` generic parameter
+
+```tsx
+// Error type is now inferred and type-safe
+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 is typed as ApiError | null
+if (error) {
+  console.log(error.status) // TypeScript knows this exists
+}
+```
+
+### New Devtools
+
+The devtools have been completely rewritten with a new design, better performance, and new features:
+
+- **Query timeline** — visualize query fetches over time
+- **Mutation inspector** — inspect mutation state and variables
+- **Cache explorer** — browse the entire query cache
+- **Online/offline toggle** — test offline behavior
+
+### Smaller Bundle Size
+
+We have reduced the core bundle size by approximately 20% through tree-shaking improvements and removing deprecated APIs.
+
+| Package | v4 | v5 | Change |
+|---|---|---|---|
+| `@tanstack/react-query` | 12.4 KB | 9.8 KB | -21% |
+| `@tanstack/query-core` | 10.1 KB | 8.2 KB | -19% |
+
+## Breaking Changes
+
+> [!WARNING]
+> v5 includes several breaking changes. Please review the full [migration guide](/en/query/docs/guides/migration-v5) before upgrading.
+
+Key breaking changes:
+
+1. **Removed overloaded signatures** — all hooks now use object-only syntax
+2. **Renamed `cacheTime` to `gcTime`** — better reflects its purpose (garbage collection time)
+3. **`status: 'loading'` renamed to `status: 'pending'`** — aligns with Promise terminology
+4. **Removed `keepPreviousData`** — replaced with `placeholderData: keepPreviousData` (import from query core)
+5. **Minimum TypeScript version is now 4.7**
+
+## Migration
+
+We have built a codemod to automate most of the migration:
+
+```bash
+npx @tanstack/query-codemod v5 ./src
+```
+
+This will handle the most common transformations automatically. Review the changes and test thoroughly.
+
+## Thank You
+
+Thank you to the 100+ contributors who made this release possible. TanStack Query v5 would not exist without the incredible open source community.
+
+Get started with v5 today:
+
+```bash
+npm install @tanstack/react-query@latest
+```
+
+Happy querying!

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

@@ -0,0 +1,26 @@
+---
+title: "Hello World: Introducing docs-i18n Blog"
+published: "2024-01-15"
+excerpt: "Welcome to the docs-i18n blog! We will share updates, tutorials, and best practices for internationalizing your documentation."
+authors:
+  - "docs-i18n Team"
+---
+
+Welcome to the docs-i18n blog! This is where we will share project updates, tutorials, and best practices for documentation internationalization.
+
+## What is docs-i18n?
+
+docs-i18n is a universal documentation translation engine that makes it easy to maintain multilingual documentation sites. It provides:
+
+- **Filesystem-based content loading** with i18n fallback
+- **Markdown rendering** with syntax highlighting and framework-aware content
+- **Admin interface** for managing translations
+- **CLI tools** for automating translation workflows
+
+## Getting Started
+
+Check out our [getting started guide](/en/getting-started) to learn how to set up docs-i18n for your project.
+
+## Stay Tuned
+
+We have exciting features planned for upcoming releases. Follow this blog for the latest updates!

package/template/content/blog/en/i18n-best-practices.md

@@ -0,0 +1,57 @@
+---
+title: "Best Practices for Documentation i18n"
+published: "2024-02-10"
+excerpt: "Learn the key principles and patterns for effectively internationalizing your documentation, from content structure to translation workflows."
+authors:
+  - "docs-i18n Team"
+---
+
+Internationalizing documentation is more than just translating text. Here are the best practices we have learned from building docs-i18n.
+
+## Structure Content for Translation
+
+### Use English as Source of Truth
+
+Keep your English content as the canonical source. All translations derive from it, and the system falls back to English when a translation is missing.
+
+### Separate Content from Presentation
+
+Store your documentation as plain markdown files organized by locale:
+
+```
+content/
+  blog/
+    en/
+      my-post.md
+    zh-hans/
+      my-post.md
+    ja/
+      my-post.md
+```
+
+### Use Frontmatter for Metadata
+
+Each document should have frontmatter with at least a `title` field. For blog posts, include `published`, `excerpt`, and `authors`.
+
+## Translation Workflow
+
+### Start with High-Impact Pages
+
+Not all pages need translation at once. Prioritize:
+
+1. Getting started guides
+2. Core concept documentation
+3. API reference
+4. Blog posts and announcements
+
+### Leverage Fallback Content
+
+docs-i18n automatically falls back to English when a translation is missing. This means your site works for all locales immediately — translations improve it incrementally.
+
+### Keep Translations in Sync
+
+When the English source changes, translations may become outdated. Use the docs-i18n admin interface to track which translations need updating.
+
+## Conclusion
+
+Good documentation internationalization is an ongoing process. Start simple, prioritize high-impact content, and iterate.

package/template/content/blog/en/react-query-vs-swr.md

@@ -0,0 +1,100 @@
+---
+title: "TanStack Query vs SWR: A Detailed Comparison"
+published: "2024-06-15"
+excerpt: "An honest, detailed comparison of TanStack Query and SWR — two of the most popular data fetching libraries in the React ecosystem."
+authors:
+  - "docs-i18n Team"
+---
+
+Choosing a data fetching library is an important architectural decision. TanStack Query and SWR are the two most popular options in the React ecosystem. Here is an honest comparison to help you decide.
+
+## Overview
+
+Both libraries solve the same core problem: managing server state in React applications. They both provide hooks for fetching, caching, and synchronizing server data. However, they differ significantly in scope and philosophy.
+
+| Feature | TanStack Query | SWR |
+|---|---|---|
+| Bundle size (minified + gzip) | ~12 KB | ~4 KB |
+| Framework support | React, Vue, Solid, Svelte, Angular | React only |
+| Devtools | Built-in, feature-rich | Community extension |
+| Mutations | First-class `useMutation` | Manual implementation |
+| Infinite queries | Built-in `useInfiniteQuery` | Built-in `useSWRInfinite` |
+| Offline support | Built-in | Manual |
+| Query cancellation | Built-in with AbortSignal | Manual |
+| Garbage collection | Configurable `gcTime` | No automatic GC |
+| Optimistic updates | Built-in helpers | Manual |
+
+## Data Fetching
+
+Both libraries make basic data fetching simple:
+
+```tsx
+// TanStack Query
+import { useQuery } from '@tanstack/react-query'
+
+function Todos() {
+  const { data, isLoading } = useQuery({
+    queryKey: ['todos'],
+    queryFn: () => fetch('/api/todos').then((r) => r.json()),
+  })
+}
+
+// SWR
+import useSWR from 'swr'
+
+function Todos() {
+  const { data, isLoading } = useSWR('/api/todos', (url) =>
+    fetch(url).then((r) => r.json())
+  )
+}
+```
+
+SWR has a slightly more concise API for simple cases. TanStack Query requires explicit query keys and uses an object syntax exclusively.
+
+## Mutations
+
+This is where the libraries diverge significantly. TanStack Query provides a dedicated `useMutation` hook:
+
+```tsx
+// TanStack Query — built-in mutation support
+const mutation = useMutation({
+  mutationFn: (newTodo) => fetch('/api/todos', {
+    method: 'POST',
+    body: JSON.stringify(newTodo),
+  }),
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+
+// Provides isPending, isError, isSuccess, mutate, mutateAsync
+mutation.mutate({ title: 'New Todo' })
+```
+
+SWR does not have a built-in mutation hook. You typically use `useSWRMutation` from the `swr/mutation` module or handle mutations manually.
+
+## When to Choose TanStack Query
+
+Choose TanStack Query when:
+
+- You need first-class mutation support with optimistic updates
+- You want built-in devtools for debugging
+- Your app has complex caching requirements
+- You need offline support
+- You might switch frameworks in the future (Vue, Solid, etc.)
+
+## When to Choose SWR
+
+Choose SWR when:
+
+- Bundle size is critical
+- You have simple data fetching needs without complex mutations
+- You prefer a minimal API surface
+- You are already in the Vercel/Next.js ecosystem
+
+## Conclusion
+
+Both are excellent libraries. TanStack Query is more feature-rich and better suited for complex applications with lots of mutations and caching needs. SWR is lighter and simpler, ideal for applications with straightforward data fetching requirements.
+
+> [!NOTE]
+> This comparison is based on TanStack Query v5 and SWR v2. Both libraries are actively maintained and improve with each release.

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.