docs-i18n 0.8.1 → 0.8.2

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" }
+      ]
+    }
+  ]
+}

package/template/content/docs-i18n/en/architecture.md

@@ -0,0 +1,222 @@
+---
+title: Architecture
+description: How docs-i18n works internally -- the translation pipeline, AST parsing, caching, and chunking strategies.
+---
+
+# Architecture
+
+This document explains how docs-i18n works internally. Understanding the pipeline helps you tune configuration, debug issues, and contribute to the project.
+
+## Translation Pipeline
+
+The end-to-end flow is:
+
+```
+Source files (EN)
+    |
+    v
+[1. Normalize] -- Ensure JSX tags are separated by blank lines
+    |
+    v
+[2. Parse] -- remark AST -> flat list of typed nodes
+    |
+    v
+[3. Hash] -- MD5 of each translatable node's text
+    |
+    v
+[4. Chunk] -- Group nodes into chunks that fit the LLM context window
+    |
+    v
+[5. Translate] -- Send JSON to LLM, receive JSON translations
+    |
+    v
+[6. Cache] -- Store translations in SQLite keyed by (lang, md5)
+    |
+    v
+[7. Assemble] -- EN source + cache -> translated output files
+```
+
+## Step 1: Normalization
+
+The `normalize()` function (`src/core/normalize.ts`) preprocesses MDX content to ensure that JSX tags like `<AppOnly>`, `<PagesOnly>`, `<details>`, and `<div>` are separated from surrounding content by blank lines. This ensures remark parses them as independent HTML nodes rather than merging them with adjacent text.
+
+For example, this input:
+
+```
+<AppOnly>
+Some text here
+</AppOnly>
+```
+
+Becomes:
+
+```
+<AppOnly>
+
+Some text here
+
+</AppOnly>
+```
+
+## Step 2: AST Parsing
+
+The `parseMdx()` function (`src/core/parser.ts`) uses remark to parse markdown into a flat list of `ParsedNode` objects. Each node has:
+
+- `type` -- The AST node type: `paragraph`, `heading`, `list`, `blockquote`, `code`, `html`, `thematicBreak`, or `frontmatter`.
+- `rawText` -- The raw text content from the normalized source.
+- `needsTranslation` -- Whether this node contains human-readable text.
+- `md5` -- MD5 hash of the raw text (only for translatable nodes).
+- `startOffset` / `endOffset` -- Character offsets in the normalized content.
+
+**Translatable node types:** `paragraph`, `heading`, `list`, `blockquote`, and `html` nodes that contain non-tag text (e.g., `<summary>Examples</summary>`).
+
+**Non-translatable:** `code` blocks, `thematicBreak`, and pure HTML/JSX tags (self-closing tags like `<Check size={18} />`, opening/closing tags like `<AppOnly></AppOnly>`).
+
+**Frontmatter handling:** If the content starts with `---`, the parser detects YAML frontmatter and emits it as a single `frontmatter` node spanning from the opening `---` to the closing `---`. The frontmatter module (`src/core/frontmatter.ts`) then extracts only the configured translatable fields (e.g., `title`, `description`) using the `yaml` library, sends them to the LLM as plain text, and reconstructs the YAML with translated values while preserving all other fields and formatting.
+
+## Step 3: MD5 Hashing
+
+Each translatable node's raw text is hashed with MD5 to produce a stable key. This key is used for:
+
+- **Deduplication** -- identical content appearing in multiple files (or even multiple projects) shares a single translation.
+- **Incremental updates** -- when source content changes, only the nodes with new MD5 hashes need translation. Unchanged nodes reuse their cached translations.
+- **Heading differentiation** -- heading nodes include their level markers (`##`, `###`) in the hash, so "## Installation" and "### Installation" produce different keys.
+
+## Step 4: Smart Chunking
+
+The translate command groups untranslated nodes into chunks that fit within the LLM's context window. The chunking algorithm (`src/commands/translate.ts`) accounts for:
+
+- **Input budget** -- system prompt tokens + source text tokens. Estimated at `text.length / 4 + 80` tokens per node (accounting for JSON structure overhead).
+- **Output budget** -- translated text tokens. Scaled by a per-language multiplier since different languages use tokens differently:
+
+| Language | Multiplier | Reason |
+| --- | --- | --- |
+| Japanese, Korean, Hindi, Thai | 2.5x | CJK/Indic tokenization |
+| Russian, Arabic, Ukrainian, Hebrew | 2.0x | Cyrillic/Arabic scripts |
+| Chinese (Simplified/Traditional) | 1.5x | CJK but more concise |
+| German, French, Portuguese | 1.3x | Slightly longer than English |
+| Spanish, Vietnamese | 1.2x | Close to English length |
+| Other languages | 2.0x | Safe default |
+
+- **System prompt overhead** -- approximately 700 tokens for the translation prompt.
+- **JSON structure overhead** -- approximately 80 tokens per key for JSON schema properties.
+- **Safety margin** -- 85% of input budget and 75% of output budget are used to leave room for estimation errors.
+
+When a chunk reaches its budget, a new chunk is started. This prevents context window overflow and output truncation.
+
+## Step 5: LLM Translation
+
+The translator (`src/core/translator.ts`) uses structured JSON mode for translations:
+
+**Input format:** A JSON object with a `nodes` array. Each node has a `key` (MD5), `type` (heading/paragraph/list/etc.), and `text` (content to translate).
+
+```json
+{
+  "nodes": [
+    { "key": "a1b2c3...", "type": "heading", "text": "## Installation" },
+    { "key": "d4e5f6...", "type": "paragraph", "text": "Run the following command:" }
+  ]
+}
+```
+
+**Output format:** A flat JSON object mapping each key to its translation.
+
+```json
+{
+  "a1b2c3...": "## \u5b89\u88c5",
+  "d4e5f6...": "\u8fd0\u884c\u4ee5\u4e0b\u547d\u4ee4\uff1a"
+}
+```
+
+**Robustness features:**
+
+- **JSON repair** -- Handles common LLM JSON errors: unescaped newlines in strings, trailing commas, missing closing braces.
+- **Thinking block stripping** -- Removes `<think>...</think>` blocks from reasoning models.
+- **Unwrapping** -- If the model wraps output in `{"nodes": {...}}` or `{"translations": {...}}`, it is automatically unwrapped.
+- **Key recovery** -- If the model corrupts an MD5 key (e.g., truncates it), the translator attempts fuzzy matching to recover the translation (up to 3 character differences).
+- **Garbage detection** -- If more than 50% of translation values are identical, the model output is rejected.
+- **Retry with backoff** -- Retries on 429 (rate limit), 503, 405, timeout, and connection errors. Uses exponential backoff starting at 2 seconds.
+- **Model rotation** -- Supports a list of models to rotate through. Dead models (400/404 errors) are skipped. Rate-limited models (429) are deprioritized.
+- **Truncation detection** -- If `finish_reason` is `'length'`, the output was truncated and the request is retried.
+
+**Frontmatter translation:**
+
+Frontmatter nodes are handled specially. Instead of sending the entire YAML block, the translator extracts individual translatable fields (e.g., `title`, `description`) and sends them as plain `paragraph` type nodes with virtual keys like `fm:<md5>:title`. After translation, the fields are reassembled into the original YAML structure using `reconstructFrontmatter()`.
+
+## Step 6: SQLite Cache
+
+The `TranslationCache` class (`src/core/cache.ts`) manages all persistent state in a single SQLite database at `<cacheDir>/translations.db`.
+
+**Schema:**
+
+```sql
+-- EN source texts (deduplicated by MD5)
+CREATE TABLE sources (
+  key   TEXT PRIMARY KEY NOT NULL,  -- MD5 hash
+  text  TEXT NOT NULL,              -- original English text
+  type  TEXT NOT NULL DEFAULT 'paragraph'
+);
+
+-- Which files use each source node
+CREATE TABLE source_files (
+  key     TEXT    NOT NULL,  -- MD5 hash
+  file    TEXT    NOT NULL,  -- relative file path
+  line    INTEGER NOT NULL,  -- line number
+  version TEXT    NOT NULL DEFAULT 'latest',
+  PRIMARY KEY (version, key, file, line)
+);
+
+-- Translated texts per language
+CREATE TABLE translations (
+  lang       TEXT    NOT NULL,  -- language code
+  key        TEXT    NOT NULL,  -- MD5 hash
+  value      TEXT    NOT NULL,  -- translated text
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  PRIMARY KEY (lang, key)
+);
+```
+
+**Performance configuration:**
+
+- **WAL mode** -- Write-Ahead Logging enables concurrent readers with a single writer. No locking issues during parallel translation and assembly.
+- **busy_timeout = 5000** -- Wait up to 5 seconds for a lock before failing.
+- **synchronous = NORMAL** -- Balanced between safety and performance.
+- **WITHOUT ROWID** -- Tables use the primary key directly, avoiding an extra rowid column.
+- **Immediate writes** -- All `set()` calls write directly to disk. No explicit save step needed.
+
+**Key operations:**
+
+- `get(lang, md5)` -- Look up a cached translation.
+- `set(lang, md5, translation)` -- Store or update a translation (upsert).
+- `untranslatedKeys(lang, version)` -- Find all source keys that have no translation for a given language.
+- `fileCoverage(version, lang)` -- Get per-file translation coverage (used by the admin dashboard).
+- `prune(lang, usedMd5s)` -- Remove translations whose keys are no longer referenced.
+- `exportJsonl(lang, outputPath)` / `importJsonl(lang, inputPath)` -- Export/import translations in JSONL format for backup or migration.
+
+**SQLite compatibility:**
+
+The `openDatabase()` function (`src/core/sqlite.ts`) automatically detects the runtime environment. Under Bun, it uses `bun:sqlite`. Under Node.js, it uses `better-sqlite3`. Both expose the same interface.
+
+## Step 7: Assembly
+
+The `assemble()` function (`src/core/assembler.ts`) produces a translated file from English source content and cached translations:
+
+1. Normalizes the source content.
+2. Parses it into AST nodes.
+3. For each node:
+   - **Non-translatable nodes** (code blocks, HTML tags) are kept as-is.
+   - **Translatable nodes with a cached translation** are replaced with the cached value.
+   - **Translatable nodes without a cache hit** are either wrapped in `<!-- NEEDS_TRANSLATION -->` markers (for the legacy whole-file translation mode) or fall back to the original English text (for assembled output files).
+4. Preserves all whitespace and newlines between nodes.
+
+The `AssembleResult` includes statistics: `cachedCount`, `uncachedCount`, `totalTranslatable`, and whether all nodes were cached (`allCached`).
+
+## Validation
+
+The `validate()` function (`src/core/validator.ts`) compares LLM output against the translation cache to detect and correct modifications to already-cached translations. It uses two alignment strategies:
+
+- **Fast path** -- When the number of translatable nodes in the source and output match, nodes are aligned by index.
+- **Anchor-based alignment** -- When node counts differ (the LLM merged or split paragraphs), cached translations serve as anchor points. The validator finds exact matches between output text and cached translations, then aligns nodes between anchors by type matching.
+
+Cached translations always override LLM modifications, ensuring translation consistency across runs.