dify-docs/CLAUDE.md

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

Translation System

Language Configuration

All language settings in tools/translate/config.json (single source of truth):

{
  "source_language": "en",
  "target_languages": ["cn", "jp"],
  "languages": {
    "en": {"code": "en", "name": "English", "directory": "en"},
    "cn": {
      "code": "cn",
      "name": "Chinese",
      "directory": "cn",
      "translation_notice": "<Note>⚠️ AI translation...</Note>"
    }
  }
}

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

First-Time Contributor Approval Flow

For PRs from forks by contributors who are not OWNER/MEMBER/COLLABORATOR:

1. PR opened → Analyze workflow runs → Execute workflow checks for approval
2. No approval found → Execute skips translation, posts "pending approval" comment
3. Maintainer approves PR → sync_docs_on_approval.yml triggers automatically
4. "Approval received" comment posted → Analyze workflow re-runs with fresh artifacts
5. Execute workflow runs → Finds approval → Creates translation PR

Approval requirements:

• Reviewer must have OWNER, MEMBER, or COLLABORATOR association
• Approval triggers immediate translation (no additional push needed)
• Each approval posts a new comment preserving the timeline

Edge cases:

• If translation PR already exists when approval happens → info comment posted, no re-run
• If Analyze run is too old to re-run → error comment with instructions to push a small commit
• Internal PRs (same repo, not fork) → no approval gate, auto-translates immediately

Manual trigger: If approval flow fails, maintainers can manually trigger via Actions → Execute Documentation Sync → Run workflow (enter PR number)

Development Commands

# 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

Approval flow issues (first-time contributors):

• Translation not starting after approval: Check Actions tab for Retrigger Sync on Approval workflow status
• "Could not automatically start translation": Analyze run too old - push a small commit to trigger fresh workflow
• Approval from non-maintainer: Only OWNER/MEMBER/COLLABORATOR approvals unlock the gate
• Multiple "pending approval" comments: Normal - each commit triggers Execute which posts if no approval found

Translation A/B Testing

For comparing translation quality between models or prompt variations:

cd tools/translate-test-dify
./setup.sh
source venv/bin/activate
python run_test.py <spec.md>
python compare.py results/<folder>/

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_analyze.yml - Analyzes PR changes, uploads artifacts
• .github/workflows/sync_docs_execute.yml - Creates translation PRs (triggered by Analyze)
• .github/workflows/sync_docs_update.yml - Updates existing translation PRs
• .github/workflows/sync_docs_cleanup.yml - Cleans up sync PRs when original PR closes
• .github/workflows/sync_docs_on_approval.yml - Retriggers translation on maintainer approval