From 8b439f3479825be3ff54044272d834e1149b0036 Mon Sep 17 00:00:00 2001 From: Gu Date: Thu, 6 Nov 2025 12:24:40 -0800 Subject: [PATCH] docs: update CLAUDE.md with surgical reconciliation and streamline content - Add comprehensive surgical reconciliation documentation (move & rename) - Document index-based navigation approach for language-independent group matching - Add move/rename to auto-sync operations list - Expand testing section with move/rename test scenarios - Add troubleshooting for move/rename issues with success log patterns - Remove outdated/unnecessary sections (plugin docs, content guidelines reference) - Streamline language config examples - Keep only essential information for working with translation system --- CLAUDE.md | 166 ++++++++++++++++++++++++------------------------------ 1 file changed, 73 insertions(+), 93 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 724af1cc..83801cd2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,24 +4,19 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -This is the Dify documentation repository built with Mintlify, supporting multi-language documentation (English, Chinese, Japanese) with automatic translation capabilities powered by Dify AI workflows. +Dify documentation repository built with Mintlify, supporting multi-language documentation (English, Chinese, Japanese) with AI-powered automatic translation via Dify workflows. ## Documentation Structure -### Content Organization -- **Format**: MDX files with YAML frontmatter (title, description required) -- **Languages**: - - General docs: `en/`, `cn/`, `jp/` - - Plugin dev docs: `plugin-dev-en/`, `plugin-dev-zh/`, `plugin-dev-ja/` - - Versioned docs: `versions/{version}/{lang}/` -- **Configuration**: `docs.json` (navigation, theme, settings) - see [Mintlify docs.json schema](https://mintlify.com/docs.json) +- **Format**: MDX files with YAML frontmatter (`title` and `description` required) +- **Languages**: `en/`, `cn/`, `jp/` (source: en) +- **Configuration**: `docs.json` (navigation structure) - [Mintlify schema](https://mintlify.com/docs.json) -### Translation System Architecture +## Translation System -AI-powered translation system that automatically translates English documentation to Chinese (cn) and Japanese (jp). +### Language Configuration -**Language Configuration** (`tools/translate/config.json`): -All language settings are centralized in a single config file. No code changes needed to add/modify languages. +All language settings in `tools/translate/config.json` (single source of truth): ```json { @@ -33,67 +28,62 @@ All language settings are centralized in a single config file. No code changes n "code": "cn", "name": "Chinese", "directory": "cn", - "translation_notice": "⚠️ AI translation notice..." - } - }, - "versioned_docs": { - "3-2-x": { - "en": "versions/3-2-x/en-us", - "cn": "versions/3-2-x/zh-cn", - "jp": "versions/3-2-x/jp" + "translation_notice": "⚠️ AI translation..." } } } ``` -**Adding a new language**: Edit `config.json` only (e.g., add Korean): -```json -{ - "target_languages": ["cn", "jp", "ko"], - "languages": { - "ko": { - "code": "ko", - "name": "Korean", - "directory": "ko", - "translation_notice": "..." - } - } -} -``` +**Adding new language**: Edit config.json only - add to `target_languages` and `languages` object with required fields. -**Workflow**: -- Trigger: Push to non-main branches with `.md/.mdx` changes in source language directory -- Process: Dify API (streaming mode) with terminology database -- New files: ~30-60s per language | Modified files: ~2-3min per language (context-aware) -- Auto-inserts translation notices from config -- Incremental docs.json sync (only changed files, preserves structure) +### Workflow -**Key Files**: `sync_and_translate.py`, `.github/workflows/sync_docs_*.yml`, `config.json` +- **Trigger**: Push to non-main branches with `.md/.mdx` changes in `en/` +- **Process**: Dify API streaming mode with terminology database (`termbase_i18n.md`) +- **Timing**: New files ~30-60s/lang | Modified files ~2-3min/lang (context-aware with git diff) +- **Auto-operations**: Translation notices, incremental docs.json sync -### Plugin Documentation Sync +### Surgical Reconciliation (Move & Rename) -Plugin development docs maintain cross-language file mappings in `plugin-dev-{lang}/sync/plugin_mappings.json`: -- Maps equivalent files across languages -- Tools: `sync_all_mdx_files_to_json.py`, `check_mapping_consistency.py`, `view_file_mappings.py` +**Purpose**: Detect and apply structural changes (moves, renames) from English section to cn/jp automatically. + +**How it works**: +1. Compares English section between base commit and HEAD +2. Detects **moves** (same file, different `group_path`) and **renames** (deleted+added in same location) +3. Applies identical operations to cn/jp using **index-based navigation** + +**Index-based navigation**: +- Groups matched by position index, not name (works across translations: "Nodes" ≠ "节点") +- Location tracked as `group_indices: [0, 1]` (parent group index 0, child index 1) +- Navigates nested structures regardless of translated group names + +**Rename specifics**: +- Detects file extension (.md, .mdx) from physical file +- Preserves extension when renaming cn/jp files +- Updates docs.json entries (stored without extensions) + +### Navigation Sync Behavior + +**Manual editing**: Only edit English (`en`) section in docs.json - workflow syncs to cn/jp automatically. + +**Auto-sync operations**: +- **Added files**: Fresh translation, inserted at same index position as English +- **Modified files**: Context-aware update using existing translation + git diff +- **Deleted files**: Removed from all language sections + physical files +- **Moved files**: Detected via `group_path` changes, cn/jp relocated using index-based navigation +- **Renamed files**: Detected when deleted+added in same location, physical files renamed with extension preserved ## Development Commands -### Local Development ```bash -# Install Mintlify CLI +# Local preview npm i -g mintlify - -# Start local development server (from repo root where docs.json is) mintlify dev -``` -### Translation Tools - -**Local translation** (for testing): -```bash +# Local translation testing pip install -r tools/translate/requirements.txt echo "DIFY_API_KEY=your_key" > tools/translate/.env -python tools/translate/main.py # Interactive or pass file path +python tools/translate/main.py ``` **Configuration**: @@ -101,57 +91,47 @@ python tools/translate/main.py # Interactive or pass file path - Languages: `tools/translate/config.json` - Model: Configure in Dify Studio -## Content Guidelines - -See `AGENTS.md` for detailed writing standards. Key requirements: -- Every MDX file must have frontmatter with `title` and `description` -- Use relative paths for internal links (never absolute URLs) -- Test all code examples before publishing -- Second-person voice ("you") -- Language tags on all code blocks - **Git Rules**: -- NEVER use `--no-verify` or skip pre-commit hooks -- Create new branch for new work -- Commit frequently - -## Navigation Structure (docs.json) - -**Manual editing** (when auto-translation won't work): -- Only edit English (`en`) section when adding new pages -- Auto-translation workflow syncs to `cn`/`jp` sections automatically -- File position in navigation maintained across all languages -- Use label translations from `tools/translate/config.json` for new dropdowns - -**Auto-sync behavior**: -- Added files: Fresh translation, inserted at same index position as English version -- Modified files: Context-aware translation update using existing translation + git diff -- Deleted files: Removed from all language sections, including physical files +- NEVER use `--no-verify` or skip hooks +- Create new branch for each feature/fix +- Commit frequently with descriptive messages ## Testing & Debugging -**Test translation workflow**: Create test PR with branch name `test/{operation}-{scope}` (e.g., `test/add-single-doc`) -- Add: New file with docs.json entry -- Delete: Remove file and docs.json entry -- Update: Modify existing file +### Test Translation Workflow -**Common issues**: +Create test PR with branch name `test/{operation}-{scope}`: + +- **Add**: New file + docs.json entry +- **Delete**: Remove file + docs.json entry +- **Update**: Modify existing file content +- **Move**: Move file between groups in docs.json (e.g., Getting Started → Nodes) +- **Rename**: Rename file + update docs.json entry (tests extension preservation) + +### Common Issues + +**Translation failures**: - **HTTP 504**: Verify `response_mode: "streaming"` in `main.py` (NOT `"blocking"`) - **Missing output**: Check Dify workflow has output variable `output1` - **Failed workflow**: Review Dify workflow logs for node errors +**Move/Rename issues**: +- **Not detected**: Check logs for "INFO: Detected X moves, Y renames" - if 0 when expecting changes, verify `group_path` actually changed between commits +- **Wrong location**: Structure mismatch between languages - verify group indices align (same nested structure) +- **File not found**: Extension detection failed - ensure file has .md or .mdx extension + **Success log pattern**: ``` -📥 Receiving streaming response... -🔄 Workflow started: {id} -🔄 Workflow finished with status: succeeded -✅ Translation completed successfully +INFO: Detected 1 moves, 0 renames, 0 adds, 0 deletes +INFO: Moving en/test-file from 'Dropdown > GroupA' to 'Dropdown > GroupB' +SUCCESS: Moved cn/test-file to new location +SUCCESS: Moved jp/test-file to new location ``` ## Key Paths - `docs.json` - Navigation structure -- `tools/translate/config.json` - **Language configuration (single source of truth)** -- `tools/translate/termbase_i18n.md` - Translation terminology -- `tools/translate/sync_and_translate.py` - Core translation logic -- `.github/workflows/sync_docs_*.yml` - Auto-translation workflows +- `tools/translate/config.json` - Language configuration (single source of truth) +- `tools/translate/termbase_i18n.md` - Translation terminology database +- `tools/translate/sync_and_translate.py` - Core translation + surgical reconciliation logic +- `.github/workflows/sync_docs_*.yml` - Auto-translation workflow triggers