docs-i18n 0.8.1 → 0.8.3

package/admin/dist/server/server.js

@@ -15556,29 +15556,21 @@ async function getStartManifest(matchedRoutes) {
 //#endregion
 //#region \0#tanstack-start-server-fn-resolver
 var manifest = {
-	"4e218d79545765572808c7eab33b7663d4496209c15406d0b449366905b6b83f": {
-		functionName: "fetchStatus_createServerFn_handler",
-		importer: () => import("./assets/status-CM7Azp4n.js")
-	},
-	"843cd8b59095708a5ae78198708db9850f89fd3dd3830ab236f0bd924417692f": {
-		functionName: "fetchFileCoverage_createServerFn_handler",
-		importer: () => import("./assets/status-CM7Azp4n.js")
-	},
-	"e1e7281e45375c67dbe408c58452e7482b139da60e9e361615553227dce95ee0": {
-		functionName: "fetchFileBlocks_createServerFn_handler",
-		importer: () => import("./assets/status-CM7Azp4n.js")
+	"a3d81974aeece150d4b02be5b91590b8187442ebea56be4a89dcbf053626d22b": {
+		functionName: "fetchVersion_createServerFn_handler",
+		importer: () => import("./assets/misc-y6t3-UOP.js")
 	},
-	"e1d13d8602339a95f559345ccfc82e9f843dd375ce8e9f580637c241e7e44774": {
-		functionName: "deleteCacheEntry_createServerFn_handler",
-		importer: () => import("./assets/status-CM7Azp4n.js")
+	"3bf4ba50ca8ccc3c8c60d8f2e53307a320940d68c478df494552066904c5cd74": {
+		functionName: "fetchLlmConfig_createServerFn_handler",
+		importer: () => import("./assets/misc-y6t3-UOP.js")
 	},
-	"1d8e3916f992485c62e62c3693083850b773fdff4ec54277de5a01eb98dab664": {
-		functionName: "rescanVersion_createServerFn_handler",
-		importer: () => import("./assets/status-CM7Azp4n.js")
+	"e0b4116f6b2c8d096830102e36458acf9c616a056fcdddda956a4d66984ef58c": {
+		functionName: "fetchConfig_createServerFn_handler",
+		importer: () => import("./assets/misc-y6t3-UOP.js")
 	},
-	"5080dc3f2f2309ec6981b94c431969637130c657e8a1dfb10400b4614eecc1ea": {
-		functionName: "fetchModels_createServerFn_handler",
-		importer: () => import("./assets/models-YNa3F3nn.js")
+	"a054a04356fe9987891efee8b7a11cd2dedb00f6b2e8f26d1c642e001e553d53": {
+		functionName: "openFile_createServerFn_handler",
+		importer: () => import("./assets/misc-y6t3-UOP.js")
 	},
 	"421de02ce39dde6e27cf4689e837ec072cbd01e63f8cdd5c2a3f42f0bd5ca613": {
 		functionName: "fetchJobs_createServerFn_handler",
@@ -15596,21 +15588,29 @@ var manifest = {
 		functionName: "deleteJob_createServerFn_handler",
 		importer: () => import("./assets/jobs-FXffC7LH.js")
 	},
-	"a3d81974aeece150d4b02be5b91590b8187442ebea56be4a89dcbf053626d22b": {
-		functionName: "fetchVersion_createServerFn_handler",
-		importer: () => import("./assets/misc-y6t3-UOP.js")
+	"4e218d79545765572808c7eab33b7663d4496209c15406d0b449366905b6b83f": {
+		functionName: "fetchStatus_createServerFn_handler",
+		importer: () => import("./assets/status-CM7Azp4n.js")
 	},
-	"3bf4ba50ca8ccc3c8c60d8f2e53307a320940d68c478df494552066904c5cd74": {
-		functionName: "fetchLlmConfig_createServerFn_handler",
-		importer: () => import("./assets/misc-y6t3-UOP.js")
+	"843cd8b59095708a5ae78198708db9850f89fd3dd3830ab236f0bd924417692f": {
+		functionName: "fetchFileCoverage_createServerFn_handler",
+		importer: () => import("./assets/status-CM7Azp4n.js")
 	},
-	"e0b4116f6b2c8d096830102e36458acf9c616a056fcdddda956a4d66984ef58c": {
-		functionName: "fetchConfig_createServerFn_handler",
-		importer: () => import("./assets/misc-y6t3-UOP.js")
+	"e1e7281e45375c67dbe408c58452e7482b139da60e9e361615553227dce95ee0": {
+		functionName: "fetchFileBlocks_createServerFn_handler",
+		importer: () => import("./assets/status-CM7Azp4n.js")
 	},
-	"a054a04356fe9987891efee8b7a11cd2dedb00f6b2e8f26d1c642e001e553d53": {
-		functionName: "openFile_createServerFn_handler",
-		importer: () => import("./assets/misc-y6t3-UOP.js")
+	"e1d13d8602339a95f559345ccfc82e9f843dd375ce8e9f580637c241e7e44774": {
+		functionName: "deleteCacheEntry_createServerFn_handler",
+		importer: () => import("./assets/status-CM7Azp4n.js")
+	},
+	"1d8e3916f992485c62e62c3693083850b773fdff4ec54277de5a01eb98dab664": {
+		functionName: "rescanVersion_createServerFn_handler",
+		importer: () => import("./assets/status-CM7Azp4n.js")
+	},
+	"5080dc3f2f2309ec6981b94c431969637130c657e8a1dfb10400b4614eecc1ea": {
+		functionName: "fetchModels_createServerFn_handler",
+		importer: () => import("./assets/models-YNa3F3nn.js")
 	}
 };
 async function getServerFnById(id) {

package/package.json

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

package/template/app/routes/$lang.$project.$version.docs.$.tsx

@@ -15,7 +15,8 @@ const fetchDoc = createServerFn({ method: 'GET' })
   )
   .handler(async ({ data }) => {
     const { loadDoc } = await import('~/utils/docs.server')
-    return loadDoc(data.project, data.version, data.lang, data.slug)
+    const projectConfig = findProject(data.project)
+    return loadDoc(data.project, data.version, data.lang, data.slug, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/$project/$version/docs/$')({

package/template/app/routes/$lang.$project.$version.docs.framework.$framework.$.tsx

@@ -19,11 +19,13 @@ const fetchFrameworkDoc = createServerFn({ method: 'GET' })
   )
   .handler(async ({ data }) => {
     const { loadDoc } = await import('~/utils/docs.server')
+    const projectConfig = findProject(data.project)
     return loadDoc(
       data.project,
       data.version,
       data.lang,
       `framework/${data.framework}/${data.slug}`,
+      projectConfig,
     )
   })
 

package/template/app/routes/$lang.$project.$version.docs.tsx

@@ -13,7 +13,8 @@ const fetchDocsConfig = createServerFn({ method: 'GET' })
   .inputValidator((data: { project: string; version: string }) => data)
   .handler(async ({ data }) => {
     const { loadDocsConfig } = await import('~/utils/docs.server')
-    return loadDocsConfig(data.project, data.version)
+    const projectConfig = findProject(data.project)
+    return loadDocsConfig(data.project, data.version, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/$project/$version/docs')({

package/template/app/routes/$lang.$project.docs.$.tsx

@@ -13,7 +13,8 @@ const fetchDoc = createServerFn({ method: 'GET' })
   )
   .handler(async ({ data }) => {
     const { loadDoc } = await import('~/utils/docs.server')
-    return loadDoc(data.project, data.version, data.lang, data.slug)
+    const projectConfig = findProject(data.project)
+    return loadDoc(data.project, data.version, data.lang, data.slug, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/$project/docs/$')({

package/template/app/routes/$lang.$project.docs.tsx

@@ -13,7 +13,8 @@ const fetchDocsConfig = createServerFn({ method: 'GET' })
   .inputValidator((data: { project: string; version: string }) => data)
   .handler(async ({ data }) => {
     const { loadDocsConfig } = await import('~/utils/docs.server')
-    return loadDocsConfig(data.project, data.version)
+    const projectConfig = findProject(data.project)
+    return loadDocsConfig(data.project, data.version, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/$project/docs')({

package/template/app/routes/$lang.docs.$.tsx

@@ -13,7 +13,8 @@ const fetchDoc = createServerFn({ method: 'GET' })
   )
   .handler(async ({ data }) => {
     const { loadDoc } = await import('~/utils/docs.server')
-    return loadDoc(data.project, data.version, data.lang, data.slug)
+    const projectConfig = getSingleProject()
+    return loadDoc(data.project, data.version, data.lang, data.slug, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/docs/$')({

package/template/app/routes/$lang.docs.framework.$framework.$.tsx

@@ -19,11 +19,13 @@ const fetchFrameworkDoc = createServerFn({ method: 'GET' })
   )
   .handler(async ({ data }) => {
     const { loadDoc } = await import('~/utils/docs.server')
+    const projectConfig = getSingleProject()
     return loadDoc(
       data.project,
       data.version,
       data.lang,
       `framework/${data.framework}/${data.slug}`,
+      projectConfig,
     )
   })
 

package/template/app/routes/$lang.docs.tsx

@@ -15,7 +15,8 @@ const fetchDocsConfig = createServerFn({ method: 'GET' })
   .inputValidator((data: { project: string; version: string }) => data)
   .handler(async ({ data }) => {
     const { loadDocsConfig } = await import('~/utils/docs.server')
-    return loadDocsConfig(data.project, data.version)
+    const projectConfig = getSingleProject()
+    return loadDocsConfig(data.project, data.version, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/docs')({

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

@@ -64,6 +64,7 @@ function getTranslationCache(projectRoot: string): TranslationCache | null {
 
 export function createFsLoader(
   projectRoot: string,
+  docsRoot = 'content',
   urlMapper?: (filePath: string) => string,
 ): ContentLoader {
   /** Supported markdown extensions, in priority order. */
@@ -79,10 +80,20 @@ export function createFsLoader(
     lang: string,
     slug: string,
   ): { raw: string; filePath: string } | null {
+    // Resolve content base directory using docsRoot from site config.
+    // docsRoot encodes the project-specific path (e.g. 'content/query', 'content/docs').
+    // Convention: no /en/ subdir — English source files live directly under version/.
+    // Non-English comes from .cache/ (translation assembly).
     const baseDirs = [
+      resolve(projectRoot, docsRoot, version),
+      resolve(projectRoot, docsRoot),
+      // Fallback: try content/{project}/{version} pattern
+      resolve(projectRoot, 'content', project, version),
+      resolve(projectRoot, 'content', version),
+      // Legacy: with lang subdir
       resolve(projectRoot, 'content', project, version, lang),
-      resolve(projectRoot, 'content', project, lang),
-      resolve(projectRoot, 'content', lang),
+      resolve(projectRoot, docsRoot, version, lang),
+      resolve(projectRoot, docsRoot, lang),
     ]
 
     if (!urlMapper) {

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

@@ -62,7 +62,7 @@ export function setContentLoader(loader: ContentLoader) {
 
 /**
  * Load a document with i18n fallback.
- * When projectConfig has urlMapper, creates a mapper-aware loader.
+ * Uses docsRoot from projectConfig to resolve content paths.
  */
 export async function loadDoc(
   project: string,
@@ -71,11 +71,9 @@ export async function loadDoc(
   slug: string,
   projectConfig?: ProjectConfig,
 ): Promise<LoadedDoc> {
-  if (projectConfig?.urlMapper) {
-    const loader = createFsLoader(getProjectRoot(), projectConfig.urlMapper)
-    return loader.loadDoc(project, version, lang, slug)
-  }
-  return getLoader().loadDoc(project, version, lang, slug)
+  const docsRoot = projectConfig?.docsRoot || 'content'
+  const loader = createFsLoader(getProjectRoot(), docsRoot, projectConfig?.urlMapper)
+  return loader.loadDoc(project, version, lang, slug)
 }
 
 /**
@@ -91,11 +89,13 @@ export async function loadDocsConfig(
     return loadFilesystemSidebar(project, version, projectConfig)
   }
 
-  const config = await getLoader().loadDocsConfig(project, version)
+  const docsRoot = projectConfig?.docsRoot || 'content'
+  const loader = createFsLoader(getProjectRoot(), docsRoot)
+  const config = await loader.loadDocsConfig(project, version)
   if (config) return config
 
   // Auto-scan fallback (filesystem only)
-  return autoScanDocs(getProjectRoot(), project, version)
+  return autoScanDocs(getProjectRoot(), docsRoot, project, version)
 }
 
 /** Generate sidebar from filesystem using numeric prefix ordering. */
@@ -105,10 +105,11 @@ function loadFilesystemSidebar(
   projectConfig: ProjectConfig,
 ): DocsConfig {
   const root = getProjectRoot()
+  const docsRoot = projectConfig.docsRoot || 'content'
   const candidates = [
-    resolve(root, 'content', project, version, 'en'),
-    resolve(root, 'content', project, 'en'),
-    resolve(root, 'content', 'en'),
+    resolve(root, docsRoot, version),
+    resolve(root, docsRoot),
+    resolve(root, 'content', project, version),
   ]
   for (const dir of candidates) {
     if (existsSync(dir) && statSync(dir).isDirectory()) {
@@ -120,17 +121,18 @@ function loadFilesystemSidebar(
 }
 
 /**
- * Auto-generate sidebar config by scanning .md files in the content directory.
+ * Auto-generate sidebar config by scanning .md/.mdx files in the content directory.
  */
 function autoScanDocs(
   root: string,
+  docsRoot: string,
   project: string,
   version: string,
 ): DocsConfig {
   const candidates = [
-    resolve(root, 'content', project, version, 'en'),
-    resolve(root, 'content', project, 'en'),
-    resolve(root, 'content', 'en'),
+    resolve(root, docsRoot, version),
+    resolve(root, docsRoot),
+    resolve(root, 'content', project, 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.