diff --git a/AGENTS.md b/AGENTS.md index a6c97c37..3cf00e69 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,11 @@ # Mintlify documentation +This file provides guidance when working with the Dify documentation repository. + +## Project Overview + +Dify documentation repository built with Mintlify, supporting multi-language documentation (English, Chinese, Japanese) with AI-powered automatic translation via Dify workflows. + ## Working relationship - You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so - ALWAYS ask for clarification rather than making assumptions @@ -10,6 +16,12 @@ - Config: docs.json for navigation, theme, settings - Components: Mintlify components +## Documentation Structure + +- **Format**: MDX files with YAML frontmatter (`title` and `description` required) +- **Languages**: `en/`, `zh/`, `ja/` (source: en) +- **Configuration**: `docs.json` (navigation structure) - [Mintlify schema](https://mintlify.com/docs.json) + ## Content strategy - Document just enough for user success - not too much, not too little - Prioritize accuracy and usability @@ -18,10 +30,6 @@ - Check existing patterns for consistency - Start by making the smallest reasonable changes -## docs.json - -- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation - ## Frontmatter requirements for pages - title: Clear, descriptive page title - description: Concise summary for SEO/navigation @@ -36,15 +44,158 @@ - Alt text on all images - Relative paths for internal links +## Translation System + +### Language Configuration + +All language settings in `tools/translate/config.json` (single source of truth): + +```json +{ + "source_language": "en", + "target_languages": ["zh", "ja"], + "languages": { + "en": {"code": "en", "name": "English", "directory": "en"}, + "zh": { + "code": "zh", + "name": "Chinese", + "directory": "zh", + "translation_notice": "⚠️ AI translation..." + }, + "ja": { + "code": "ja", + "name": "Japanese", + "directory": "ja", + "translation_notice": "⚠️ AI translation..." + } + } +} +``` + +**Adding new language**: Edit config.json only - add to `target_languages` and `languages` object with required fields (`code`, `name`, `directory`, `translation_notice`). + +### Workflow + +- **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 + +### Surgical Reconciliation (Move & Rename) + +**Purpose**: Detect and apply structural changes (moves, renames) from English section to zh/ja 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 zh/ja 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 zh/ja files +- Updates docs.json entries (stored without extensions) + +### Navigation Sync Behavior + +**Manual editing**: Only edit English (`en`) section in docs.json - workflow syncs to zh/ja 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, zh/ja relocated using index-based navigation +- **Renamed files**: Detected when deleted+added in same location, physical files renamed with extension preserved + +## Development Commands + +```bash +# Local preview +npm i -g mintlify +mintlify dev + +# Local translation testing +pip install -r tools/translate/requirements.txt +echo "DIFY_API_KEY=your_key" > tools/translate/.env +python tools/translate/main.py +``` + +**Configuration**: +- Terminology: `tools/translate/termbase_i18n.md` +- Languages: `tools/translate/config.json` +- Model: Configure in Dify Studio + ## Git workflow -- NEVER use --no-verify when committing +- NEVER use `--no-verify` or skip hooks - Ask how to handle uncommitted changes before starting -- Create a new branch when no clear branch exists for changes +- Create new branch for each feature/fix - Commit frequently throughout development - NEVER skip or disable pre-commit hooks +## Testing & Debugging + +### Test Translation Workflow + +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**: +``` +INFO: Detected 1 moves, 0 renames, 0 adds, 0 deletes +INFO: Moving en/test-file from 'Dropdown > GroupA' to 'Dropdown > GroupB' +SUCCESS: Moved zh/test-file to new location +SUCCESS: Moved ja/test-file to new location +``` + +## Translation A/B Testing + +For comparing translation quality between models or prompt variations: + +```bash +cd tools/translate-test-dify +./setup.sh +source venv/bin/activate +python run_test.py +python compare.py results// +``` + +**Important**: +- Never commit `results/`, `mock_docs/`, or real API keys +- Always redact keys with `app-***` before committing +- See `tools/translate-test-dify/README.md` for details + +## Key Paths + +- `docs.json` - Navigation structure +- `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 +- `tools/translate-test-dify/` - Translation A/B testing framework +- `.github/workflows/sync_docs_*.yml` - Auto-translation workflow triggers + ## Do not - Skip frontmatter on any MDX file - Use absolute URLs for internal links - Include untested code examples -- Make assumptions - always ask for clarification \ No newline at end of file +- Make assumptions - always ask for clarification diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 782106a8..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,155 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -Dify documentation repository built with Mintlify, supporting multi-language documentation (English, Chinese, Japanese) with AI-powered automatic translation via Dify workflows. - -## Documentation Structure - -- **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 - -### Language Configuration - -All language settings in `tools/translate/config.json` (single source of truth): - -```json -{ - "source_language": "en", - "target_languages": ["cn", "jp"], - "languages": { - "en": {"code": "en", "name": "English", "directory": "en"}, - "cn": { - "code": "cn", - "name": "Chinese", - "directory": "cn", - "translation_notice": "⚠️ AI translation..." - } - } -} -``` - -**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 `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 - -### Surgical Reconciliation (Move & Rename) - -**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 - -```bash -# Local preview -npm i -g mintlify -mintlify dev - -# Local translation testing -pip install -r tools/translate/requirements.txt -echo "DIFY_API_KEY=your_key" > tools/translate/.env -python tools/translate/main.py -``` - -**Configuration**: -- Terminology: `tools/translate/termbase_i18n.md` -- Languages: `tools/translate/config.json` -- Model: Configure in Dify Studio - -**Git Rules**: -- 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}`: - -- **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**: -``` -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 -``` - -## Translation A/B Testing - -For comparing translation quality between models or prompt variations: - -```bash -cd tools/translate-test-dify -./setup.sh -source venv/bin/activate -python run_test.py -python compare.py results// -``` - -**Important**: -- Never commit `results/`, `mock_docs/`, or real API keys -- Always redact keys with `app-***` before committing -- See `tools/translate-test-dify/README.md` for details - -## Key Paths - -- `docs.json` - Navigation structure -- `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 -- `tools/translate-test-dify/` - Translation A/B testing framework -- `.github/workflows/sync_docs_*.yml` - Auto-translation workflow triggers diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 00000000..47dc3e3d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file