Add exclude_dirs support for translation system (#894)

Author: ewels

TRANSLATING.md

@@ -190,6 +190,19 @@ flowchart TD
 - The system uses the last merged translation PR's commit SHA as the baseline for change detection
 - **Translation PRs should be merged promptly** to avoid them stacking up or becoming outdated
 
+### Excluding Directories from Translation
+
+To prevent specific directories under `docs/en/docs/` from being translated, add them to `_scripts/translate/translate_config.yml`:
+
+```yaml
+exclude_dirs:
+  - example_docs_set
+  - archive
+```
+
+Excluded directories are skipped during sync (both new and outdated detection) and are not flagged as orphaned.
+Pages in excluded directories still appear on translated sites, showing the English content with a "Translation in Progress" admonition.
+
 ---
 
 ## Reviewing Translation PRs
@@ -413,6 +426,7 @@ _scripts/
 │   ├── __init__.py         # Package marker
 │   ├── __main__.py         # Entry point
 │   ├── config.py           # Constants and configuration
+│   ├── translate_config.yml# Translation scope config (exclude dirs, etc.)
 │   ├── models.py           # Data structures
 │   ├── paths.py            # Path utilities
 │   ├── prompts.py          # Prompt loading

_scripts/translate/config.py

@@ -3,15 +3,18 @@
 from __future__ import annotations
 
 import os
+from functools import lru_cache
 from pathlib import Path
 
+import yaml
 from rich.console import Console
 
 # Paths (resolved relative to this file: _scripts/translate/config.py)
 REPO_ROOT = Path(__file__).parent.parent.parent
 DOCS_ROOT = REPO_ROOT / "docs"
 EN_DOCS = DOCS_ROOT / "en" / "docs"
 SCRIPTS_DIR = REPO_ROOT / "_scripts"
+TRANSLATE_CONFIG = Path(__file__).parent / "translate_config.yml"
 
 # Claude API settings
 MODEL = "claude-sonnet-4-6"
@@ -28,6 +31,23 @@
 DEFAULT_PARALLEL = 10
 PRIORITY_DIRS = ["hello_nextflow", "hello_nf-core", "nf4_science", "envsetup"]
 
+
+@lru_cache
+def get_translate_config() -> dict:
+    """Load translation configuration from translate_config.yml."""
+    if not TRANSLATE_CONFIG.exists():
+        return {}
+    data = yaml.safe_load(TRANSLATE_CONFIG.read_text(encoding="utf-8"))
+    return data if isinstance(data, dict) else {}
+
+
+def get_exclude_dirs() -> set[str]:
+    """Return the set of directory names to exclude from translation."""
+    cfg = get_translate_config()
+    dirs = cfg.get("exclude_dirs", [])
+    return set(dirs) if isinstance(dirs, list) else set()
+
+
 # Comment styles by language (used for code block post-processing)
 HASH_COMMENT_LANGS = {"python", "py", "sh", "bash", "dockerfile", "yaml", "yml", "toml"}
 SLASH_COMMENT_LANGS = {"console"}  # Note: json has no comments

_scripts/translate/git_utils.py

@@ -9,7 +9,14 @@
 
 import git
 
-from .config import DOCS_ROOT, REPO_ROOT, SCRIPTS_DIR, ConfigError
+from .config import (
+    DOCS_ROOT,
+    EN_DOCS,
+    REPO_ROOT,
+    SCRIPTS_DIR,
+    ConfigError,
+    get_exclude_dirs,
+)
 from .models import TranslationFile
 from .paths import en_to_lang_path, iter_en_docs, lang_to_en_path
 
@@ -217,11 +224,24 @@ def get_missing_files(lang: str) -> list[TranslationFile]:
 
 
 def get_orphaned_files(lang: str) -> list[Path]:
-    """Find translation files without English source."""
+    """Find translation files without English source.
+
+    Translations in excluded directories are not flagged as orphaned,
+    since their English sources are intentionally skipped.
+    """
     lang_docs = DOCS_ROOT / lang / "docs"
     if not lang_docs.exists():
         return []
-    return [p for p in lang_docs.rglob("*.md") if not lang_to_en_path(p, lang).exists()]
+    exclude_dirs = get_exclude_dirs()
+    orphaned = []
+    for p in lang_docs.rglob("*.md"):
+        # Skip files in excluded directories
+        rel = p.relative_to(lang_docs)
+        if rel.parts and rel.parts[0] in exclude_dirs:
+            continue
+        if not lang_to_en_path(p, lang).exists():
+            orphaned.append(p)
+    return orphaned
 
 
 def get_renamed_files(baseline: str) -> dict[Path, Path]:

_scripts/translate/paths.py

@@ -7,7 +7,7 @@
 
 import yaml
 
-from .config import DOCS_ROOT, EN_DOCS, PRIORITY_DIRS, ConfigError
+from .config import DOCS_ROOT, EN_DOCS, PRIORITY_DIRS, ConfigError, get_exclude_dirs
 
 
 @lru_cache
@@ -41,17 +41,27 @@ def lang_to_en_path(lang_path: Path, lang: str) -> Path:
     return EN_DOCS / lang_path.relative_to(DOCS_ROOT / lang / "docs")
 
 
+def _is_excluded(path: Path, exclude_dirs: set[str]) -> bool:
+    """Check if a path falls under an excluded directory."""
+    if not exclude_dirs:
+        return False
+    rel = path.relative_to(EN_DOCS)
+    return bool(rel.parts) and rel.parts[0] in exclude_dirs
+
+
 def iter_en_docs() -> list[Path]:
     """List all English docs in priority order.
 
     Priority directories are listed first, then remaining files.
     Within each group, files are sorted alphabetically.
+    Directories listed in translate_config.yml ``exclude_dirs`` are skipped.
     """
+    exclude_dirs = get_exclude_dirs()
     paths: list[Path] = []
     seen: set[Path] = set()
 
     def add(p: Path) -> None:
-        if p not in seen:
+        if p not in seen and not _is_excluded(p, exclude_dirs):
             paths.append(p)
             seen.add(p)
 

_scripts/translate/translate_config.yml

@@ -0,0 +1,8 @@
+# Translation configuration
+# Controls which English documentation files are included in automatic translation.
+
+# Directories under docs/en/docs/ to exclude from translation.
+# Files in these directories will not be translated, and existing
+# translations will not be flagged as orphaned.
+# Example: ["side_quests", "archive"]
+exclude_dirs: []