New Crowdin updates

README.md

@@ -57,11 +57,12 @@ swa start _site
 1. **Generates DocFX configurations** - Runs `gen_redirects.py` to create `docfx.json` for each language
 2. **Generates language manifest** - Creates `metadata/languages.json` for runtime language switching
 3. **Syncs content** - Copies English source to `localizedContent/en/`. For other languages, only shared directories (assets, api) are synced by default since Crowdin manages translations. Use `--sync` to enable full English fallback for missing/outdated translations (useful for local development).
-4. **Builds documentation** - Runs DocFX for each requested language
-5. **Fixes API docs** - Patches xref links in generated API documentation
-6. **Copies API docs** - Shares English API docs with localized sites
-7. **Injects SEO tags** - Adds hreflang and canonical tags to HTML files
-8. **Generates SWA config** - Creates `staticwebapp.config.json` for Azure Static Web Apps routing
+4. **Normalizes DocFX alerts** - Runs `normalize-localized-alerts.py` on each non-English language to repair Crowdin-collapsed Note/Tip/etc. alerts before building (see [DocFX Alerts and Translations](#docfx-alerts-and-translations))
+5. **Builds documentation** - Runs DocFX for each requested language
+6. **Fixes API docs** - Patches xref links in generated API documentation
+7. **Copies API docs** - Shares English API docs with localized sites
+8. **Injects SEO tags** - Adds hreflang and canonical tags to HTML files
+9. **Generates SWA config** - Creates `staticwebapp.config.json` for Azure Static Web Apps routing
 
 # Project Structure
 
@@ -73,7 +74,8 @@ TEDoc/
 │   ├── gen_languages.py       # Generates language manifest
 │   ├── gen_staticwebapp_config.py
 │   ├── inject_seo_tags.py
-│   └── sync-localized-content.py
+│   ├── sync-localized-content.py
+│   └── normalize-localized-alerts.py  # Repairs Crowdin-collapsed DocFX alerts
 ├── content/                   # English source content (tracked in git)
 │   └── _ui-strings.json       # English UI strings (header, footer, banners)
 ├── localizedContent/          # Build directories for all languages
@@ -117,6 +119,28 @@ To prevent this, add an `<a name="..."></a>` tag above any heading that is refer
 
 Crowdin does not translate HTML `name` attributes, so the anchor remains stable across all languages. Only add these to headings that are actually linked to — there is no need to add them to every heading.
 
+# DocFX Alerts and Translations
+
+DocFX renders styled alert boxes (Note, Tip, Important, Warning, Caution) from a two-line blockquote where the marker stands alone on the first line:
+
+```markdown
+> [!NOTE]
+> Your note text here.
+```
+
+When an alert like this is nested inside a list item, Crowdin collapses the two lines into one on export, producing `> [!NOTE]> Your note text here.`. DocFX requires the marker to be alone on its line, so the collapsed form is downgraded to a plain `<blockquote>` — losing the styled box — and the build logs an `invalid-note-section` warning. Only list-nested alerts are affected; top-level alerts round-trip through Crowdin unchanged.
+
+`build_scripts/normalize-localized-alerts.py` repairs this by splitting the collapsed form back into two lines, preserving the original indentation so the alert stays inside its list item. It is idempotent and only rewrites the exact collapsed pattern (text inside fenced code blocks is left untouched), so it is safe to run repeatedly.
+
+The build runs it automatically for each non-English language before DocFX (step 4 of [What the Build Script Does](#what-the-build-script-does)). You can also run it manually after a Crowdin pull:
+
+```bash
+python build_scripts/normalize-localized-alerts.py            # fix all languages
+python build_scripts/normalize-localized-alerts.py --dry-run  # preview without writing
+python build_scripts/normalize-localized-alerts.py --check    # exit 1 if fixes are needed (CI)
+python build_scripts/normalize-localized-alerts.py es         # fix a single language
+```
+
 # Translating UI Strings
 
 The `_ui-strings.json` file controls the text of site-wide UI elements that are not part of the documentation content itself: the header navigation, header buttons, footer text, and the AI translation warning banner. These strings are applied at runtime by the JavaScript bundle for non-English pages.
@@ -175,3 +199,4 @@ If a key is missing from a language's file, or no `_ui-strings.json` exists at a
 | `tableOfContents` | `Table of Contents` | Mobile TOC offcanvas title |
 | `selectLanguage` | `Select language` | Language picker label |
 | `copyCode` | `Copy code` | Code block copy button aria-label |
+

build-docs.py

@@ -23,25 +23,61 @@
 import argparse
 import json
 import os
+import re
 import shutil
 import subprocess
 import sys
 from pathlib import Path
 
 
-def run_command(cmd: list[str], description: str, check: bool = True) -> int:
-    """Run a command and return exit code."""
+_DOCFX_WARNING_RE = re.compile(r': warning ', re.IGNORECASE)
+
+
+def run_command(cmd: list[str], description: str, check: bool = True, fail_on_warnings: bool = False) -> int:
+    """Run a command and return exit code.
+
+    If fail_on_warnings=True, streams output line-by-line, counts DocFX warning
+    diagnostics (lines matching ': warning '), and returns exit code 1 if any
+    are found — even when the process itself exits 0.
+    """
     print(f"\n{'='*60}")
     print(f"  {description}")
     print(f"{'='*60}")
     print(f"Running: {' '.join(cmd)}\n")
-
+
+    if fail_on_warnings:
+        warning_count = 0
+        process = subprocess.Popen(
+            cmd,
+            shell=(os.name == 'nt'),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding='utf-8',
+            errors='replace'
+        )
+        for line in process.stdout:
+            print(line, end='', flush=True)
+            if _DOCFX_WARNING_RE.search(line):
+                warning_count += 1
+        process.wait()
+
+        if check and process.returncode != 0:
+            print(f"Error: Command failed with exit code {process.returncode}")
+            return process.returncode
+
+        if warning_count > 0:
+            print(f"\nError: DocFX produced {warning_count} warning(s). Failing build.")
+            return 1
+
+        return process.returncode
+
     result = subprocess.run(cmd, shell=(os.name == 'nt'))
-    
+
     if check and result.returncode != 0:
         print(f"Error: Command failed with exit code {result.returncode}")
         return result.returncode
-    
+
     return result.returncode
 
 
@@ -85,15 +121,24 @@ def prepare_localized_content(lang: str, sync: bool = False) -> int:
         )
 
     if sync:
-        return run_command(
+        result = run_command(
             [sys.executable, "build_scripts/sync-localized-content.py", "--sync", lang],
             f"Syncing {lang} content (fallback to English for outdated)"
         )
     else:
-        return run_command(
+        result = run_command(
             [sys.executable, "build_scripts/sync-localized-content.py", "--shared-only", lang],
             f"Syncing shared directories for {lang}"
         )
+    if result != 0:
+        return result
+
+    # Repair Crowdin-collapsed DocFX alerts (e.g. "> [!NOTE]> text") before docfx
+    # builds this language, so alerts render as styled boxes instead of plain quotes.
+    return run_command(
+        [sys.executable, "build_scripts/normalize-localized-alerts.py", lang],
+        f"Normalizing DocFX alerts for {lang}"
+    )
 
 
 def build_language(lang: str, sync: bool = False) -> int:
@@ -110,10 +155,13 @@ def build_language(lang: str, sync: bool = False) -> int:
     if result != 0:
         return result
 
-    # Build the documentation
+    # Build the documentation — fail on DocFX warnings only for English (the
+    # authored source). Localized content is Crowdin-managed and may carry
+    # translation warnings that must not block deployment.
     return run_command(
         ["docfx", config_path],
-        f"Building {lang} documentation"
+        f"Building {lang} documentation",
+        fail_on_warnings=(lang == "en")
     )
 
 

build_scripts/normalize-localized-alerts.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+Normalize DocFX alerts in Crowdin-translated content.
+
+Crowdin collapses DocFX/GitHub-style alerts that are nested inside list items,
+joining the marker line and the first content line. This:
+
+    > [!NOTE]
+    > text
+
+comes back from Crowdin as:
+
+    > [!NOTE]> text
+
+DocFX requires the alert marker (e.g. [!NOTE]) to stand alone on its line.
+Otherwise the parser emits an "invalid-note-section" warning and downgrades the
+alert to a plain <blockquote>, losing the styled NOTE/TIP/IMPORTANT box.
+
+This script finds the collapsed form and splits it back into two lines,
+preserving the original indentation so the alert stays inside its list item.
+It is idempotent and only rewrites the exact collapsed pattern, so it is safe
+to run after every Crowdin pull. Lines inside fenced code blocks are skipped so
+documentation that shows alert syntax verbatim is never altered.
+
+Usage:
+    python normalize-localized-alerts.py                 # fix all languages
+    python normalize-localized-alerts.py --dry-run       # preview only
+    python normalize-localized-alerts.py --check         # exit 1 if fixes needed (CI)
+    python normalize-localized-alerts.py es              # fix only Spanish
+"""
+
+import argparse
+import sys
+import re
+from pathlib import Path
+
+# localizedContent/ lives one level up from this build_scripts/ directory.
+TEDOC_ROOT = Path(__file__).resolve().parent.parent
+LOCALIZED_DIR = TEDOC_ROOT / "localizedContent"
+
+# A blockquote line where a DocFX alert marker is immediately followed by '>'
+# and inline content, e.g. "   > [!NOTE]> text". Captures the leading
+# indentation, the marker, and the trailing content.
+COLLAPSED_ALERT_RE = re.compile(r"^([ \t]*)>[ \t]?(\[![A-Za-z]+\])>[ \t]?(.*)$")
+
+# A fenced-code delimiter: 3+ backticks or 3+ tildes, optionally indented.
+# Group 1 is the run of fence characters; group 2 is any trailing text
+# (an info string on an opener; must be blank on a valid closer).
+FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})(.*)$")
+
+
+def normalize_text(text: str, newline: str) -> tuple[str, int]:
+    """Return (new_text, fixes) with collapsed alerts split into two lines.
+
+    Fenced code blocks are tracked per CommonMark so alert-looking text inside a
+    code sample is never rewritten: a fence is only *closed* by a delimiter using
+    the same character, at least as long as the opener, with no trailing text.
+    This keeps state in sync across nested/mismatched fences (e.g. a ```` block
+    that contains ``` lines, or backtick and tilde fences mixed in one file).
+    """
+    lines = text.split(newline)
+    out: list[str] = []
+    fence_char = ""  # "" when outside a fence, else the opener's char ("`"/"~")
+    fence_len = 0
+    fixes = 0
+
+    for line in lines:
+        fence = FENCE_RE.match(line)
+        if fence:
+            run, tail = fence.group(1), fence.group(2)
+            char, length = run[0], len(run)
+            if not fence_char:
+                fence_char, fence_len = char, length  # opening fence
+            elif char == fence_char and length >= fence_len and not tail.strip():
+                fence_char, fence_len = "", 0  # matching closing fence
+            # Otherwise it's a fence-looking line inside the block: leave as content.
+            out.append(line)
+            continue
+
+        if not fence_char:
+            m = COLLAPSED_ALERT_RE.match(line)
+            if m:
+                indent, marker, rest = m.group(1), m.group(2), m.group(3)
+                out.append(f"{indent}> {marker}")
+                out.append(f"{indent}> {rest}" if rest else f"{indent}>")
+                fixes += 1
+                continue
+
+        out.append(line)
+
+    return newline.join(out), fixes
+
+
+def normalize_file(path: Path, dry_run: bool) -> int:
+    """Normalize a single file in place. Returns number of alerts fixed."""
+    with open(path, "r", encoding="utf-8", newline="") as f:
+        text = f.read()
+
+    newline = "\r\n" if "\r\n" in text else "\n"
+    new_text, fixes = normalize_text(text, newline)
+
+    if fixes and not dry_run:
+        with open(path, "w", encoding="utf-8", newline="") as f:
+            f.write(new_text)
+
+    return fixes
+
+
+def iter_markdown_files(lang: str | None):
+    """Yield every .md file under localizedContent/ (optionally one language)."""
+    base = LOCALIZED_DIR / lang if lang else LOCALIZED_DIR
+    if not base.exists():
+        return
+    yield from sorted(base.rglob("*.md"))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Split Crowdin-collapsed DocFX alerts back into two lines."
+    )
+    parser.add_argument(
+        "lang", nargs="?",
+        help="Language code to fix (default: all languages under localizedContent/)",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="Show what would change without writing files",
+    )
+    parser.add_argument(
+        "--check", action="store_true",
+        help="Exit 1 if any file needs fixing (implies --dry-run). For CI.",
+    )
+    args = parser.parse_args()
+
+    dry_run = args.dry_run or args.check
+
+    if not LOCALIZED_DIR.exists():
+        print(f"Error: {LOCALIZED_DIR} not found.")
+        return 1
+
+    total_files = 0
+    total_fixes = 0
+
+    for path in iter_markdown_files(args.lang):
+        fixes = normalize_file(path, dry_run)
+        if fixes:
+            total_files += 1
+            total_fixes += fixes
+            rel = path.relative_to(LOCALIZED_DIR)
+            verb = "Would fix" if dry_run else "Fixed"
+            print(f"  {verb} {fixes} alert(s): {rel}")
+
+    if total_fixes == 0:
+        print("No collapsed alerts found. Everything is clean.")
+        return 0
+
+    action = "would be fixed" if dry_run else "fixed"
+    print(f"\n{total_fixes} alert(s) across {total_files} file(s) {action}.")
+
+    if args.check:
+        print("Run without --check to apply the fixes.")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except KeyboardInterrupt:
+        print("\nInterrupted.")
+        sys.exit(1)