Anthropic Articles Full Translation & Interpretation Implementation Plan¶

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Translate all Anthropic official articles already snapshotted under docs/books/claude-agents/sources/ into Chinese with local images, add per-article interpretations, and keep a unified index page visible in mkdocs.yml.

Architecture: Use existing snapshots for English source text, create per-article translation/interpretation Markdown files keyed by URL slug, download images into docs/assets/books/claude-agents/<slug>/, and update the unified index page to link to originals, translations, and interpretations.

Tech Stack: Markdown, Python (bs4/requests), curl, MkDocs.

Context/Constraints¶

Do not re-download or duplicate original snapshots in docs/books/claude-agents/sources/.
All images must be localized into docs/assets/books/claude-agents/<slug>/ and referenced with relative paths.
Use existing reference numbers in docs/books/claude-agents/references.md (e.g., [61], [62], [103]) in each translated article.
Keep only the unified index in nav (docs/books/claude-agents/anthropic-articles-index.md).
Required checks before completion: python3 tools/check_citations.py and mkdocs build --strict.

Task 1: Generate working manifest of remaining Anthropic articles¶

Files: - Read: docs/books/claude-agents/sources/index.jsonl - Read: docs/books/claude-agents/sources.md - Read: docs/books/claude-agents/references.md - Modify: docs/books/claude-agents/anthropic-articles-index.md

Step 1: Produce a remaining-articles checklist (slug, title, ref #, category)

Run:

python3 - <<'PY'
import json
from pathlib import Path
from urllib.parse import urlparse

entries = []
for line in Path('docs/books/claude-agents/sources/index.jsonl').read_text(encoding='utf-8').splitlines():
    data = json.loads(line)
    if 'anthropic.com/' in data.get('url',''):
        entries.append(data)

for item in entries:
    path = urlparse(item['url']).path
    slug = path.strip('/').split('/')[-1]
    print(slug, item['title'], item['url'], item['path'])
PY

Expected: list of all Anthropic items with slug and snapshot path.

Step 2: Update index to reflect progress after each batch

Re-run the existing index generator (or edit manually) after each batch.

Task 2: Engineering batch (10 remaining articles)¶

Repeat the following steps for each Engineering article not yet translated (slug list from Task 1).

Files (per article): - Read: docs/books/claude-agents/<snapshot>.md - Create: docs/books/claude-agents/<slug>.md - Create: docs/books/claude-agents/<slug>-interpretation.md - Create: docs/assets/books/claude-agents/<slug>/... - Modify: docs/books/claude-agents/anthropic-articles-index.md

Step 1: Extract images from the live page and download locally

Run (replace URL and slug each time):

python3 - <<'PY'
from bs4 import BeautifulSoup
from urllib.request import Request, urlopen
from urllib.parse import urlparse, parse_qs, unquote
from pathlib import Path

url = "https://www.anthropic.com/engineering/<slug>"
slug = "<slug>"

req = Request(url, headers={
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36"
})
html = urlopen(req).read().decode("utf-8", errors="ignore")

soup = BeautifulSoup(html, "html.parser")
article = soup.find("article")
if not article:
    print("No article content found")
    raise SystemExit(1)

out_dir = Path("docs/assets/books/claude-agents") / slug
out_dir.mkdir(parents=True, exist_ok=True)

figs = []
for fig in article.find_all("figure"):
    img = fig.find("img")
    if not img:
        continue
    src = img.get("src", "")
    if src.startswith("/_next/image"):
        q = parse_qs(urlparse(src).query)
        if "url" in q:
            src = unquote(q["url"][0])
    cap = ""
    figcap = fig.find("figcaption")
    if figcap:
        cap = figcap.get_text(" ", strip=True)
    figs.append((src, cap))

for i, (src, cap) in enumerate(figs, 1):
    if not src:
        continue
    ext = Path(urlparse(src).path).suffix or ".png"
    dest = out_dir / f"figure-{i:02d}{ext}"
    req = Request(src, headers={"User-Agent": "Mozilla/5.0"})
    with urlopen(req) as r, dest.open("wb") as f:
        f.write(r.read())
    print(dest, cap)
PY

Expected: images downloaded into docs/assets/books/claude-agents/<slug>/ and captions printed.

Step 2: Write the full Chinese translation

Use the existing snapshot file as the source text.
Preserve headings, lists, tables, and code blocks.
Insert local images with captions using:

![图：<caption>](../../assets/books/claude-agents/<slug>/figure-01.png)

Add a top header with URL, publish date, and author list, and cite the correct reference number.

Step 3: Write the interpretation page

5–8 concise bullets: 主旨、关键洞察、工程可执行要点、与本书关联、结论。
Cite the same reference number.

Step 4: Update the index

Ensure anthropic-articles-index.md points to the new translation and interpretation.

Task 3: Research batch (4 articles)¶

Repeat Task 2 for /research/ articles. Same file structure and image-localization process.

Task 4: News batch (8 articles)¶

Repeat Task 2 for /news/ articles. Same file structure and image-localization process.

Task 5: Verification¶

Step 1: Run citations check

python3 tools/check_citations.py

Expected: no missing citations.

Step 2: Run strict MkDocs build

mkdocs build --strict

Expected: build succeeds with no warnings.

Task 6: Final consistency sweep¶

Ensure all translations link to the correct snapshot and use relative .md links.
Ensure all images are local and referenced via relative paths.
Ensure mkdocs.yml includes only the unified index entry for Anthropic translations.