stanford-cs336 · HUANGTINGTING-UBAND · Jul 1, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026
diff --git a/README.md b/README.md
@@ -2,6 +2,37 @@
 
 This repository contains the lecture materials for Stanford's Language Modeling from Scratch (CS336).
 
+## Bilingual Learning Version / 中英对照学习版
+
+This branch adds a bilingual learning layer on top of the original Stanford CS336 lecture materials.
+
+本分支在 Stanford CS336 原始课程资料之上增加中英对照学习层。
+
+- The original English text is preserved.
+- 英文原文完整保留。
+- Chinese translations are provided for study and comprehension support.
+- 中文译文用于学习和辅助理解。
+- This is not an official Stanford translation.
+- 本项目不是 Stanford 官方翻译。
+- PDF lectures and text embedded inside images are not covered in the first executable-lecture translation pass.
+- 第一轮可执行讲义翻译暂不覆盖 PDF 讲义和图片内部文字。
+- Current executable lecture coverage: `lecture_01.py`, `lecture_02.py`, `lecture_06.py`, `lecture_07.py`, `lecture_10.py`, `lecture_12.py`, `lecture_13.py`, `lecture_14.py`, and `lecture_17.py`.
+- 当前可执行讲义覆盖范围：`lecture_01.py`、`lecture_02.py`、`lecture_06.py`、`lecture_07.py`、`lecture_10.py`、`lecture_12.py`、`lecture_13.py`、`lecture_14.py` 和 `lecture_17.py`。
+- Reference notes in `references.py` include Chinese study notes while preserving formal titles, authors, dates, and URLs.
+- `references.py` 中的引用说明已增加中文学习说明；正式标题、作者、日期和 URL 保持原样。
+
+Translation tracking files:
+
+- `docs/translation-inventory.md`: AST-based inventory of executable lecture text.
+- `docs/bilingual-glossary.md`: shared terminology.
+- `docs/translation-review.md`: items needing human review.
+
+翻译跟踪文件：
+
+- `docs/translation-inventory.md`：基于 AST 的可执行讲义文本盘点。
+- `docs/bilingual-glossary.md`：统一术语表。
+- `docs/translation-review.md`：需要人工复核的内容。
+
 ## Executable lectures
 
 These are named `lecture_XX.py`.

diff --git a/docs/bilingual-glossary.md b/docs/bilingual-glossary.md
@@ -0,0 +1,38 @@
+# Bilingual Glossary
+
+This glossary keeps terminology consistent across the bilingual learning version.
+
+本术语表用于保持中英对照学习版中的术语一致。
+
+| English | 中文译法 | Acceptable short form | First lecture | Notes |
+|---|---|---|---|---|
+| language model | 语言模型 | LM | lecture_01 | 首次出现保留 English term。 |
+| tokenization | 分词 | tokenizer / token | lecture_01 | 具体 tokenizer 名称不翻译。 |
+| Transformer | Transformer 架构 | Transformer | lecture_01 | 正式模型/架构名保留英文。 |
+| attention | 注意力机制 | attention | lecture_01 | 数学公式中的符号不翻译。 |
+| mixture of experts | 专家混合 | MoE | lecture_01 | 首次出现写作“专家混合（mixture of experts, MoE）”。 |
+| scaling laws | 缩放定律 | scaling laws | lecture_01 | 课程核心术语。 |
+| compute | 计算量 | compute | lecture_02 | 视上下文也可译为“算力预算”。 |
+| memory | 内存 | memory | lecture_02 | GPU 场景可译为“显存”。 |
+| FLOPs | 浮点运算次数 | FLOPs | lecture_02 | 缩写保留。 |
+| arithmetic intensity | 算术强度 | AI | lecture_02 | 避免与 artificial intelligence 混淆。 |
+| tensor | 张量 | tensor | lecture_02 | 代码变量和 shape 符号不翻译。 |
+| gradient | 梯度 | gradient | lecture_02 | 与 optimizer 相关。 |
+| optimizer | 优化器 | optimizer | lecture_02 | Adam/AdamW 等正式名称不翻译。 |
+| benchmark | 基准测试 | benchmark | lecture_06 | 正式 benchmark 名称保留英文。 |
+| profiling | 性能剖析 | profiler | lecture_06 | PyTorch profiler / Nsight 名称保留。 |
+| kernel | 核函数 | kernel | lecture_06 | GPU/Triton 语境。 |
+| inference | 推理 | inference | lecture_10 | 与 training 区分。 |
+| evaluation | 评测 | eval | lecture_12 | benchmark 名称保留英文。 |
+| data filtering | 数据过滤 | filtering | lecture_13 | 数据处理语境。 |
+| deduplication | 去重 | dedup | lecture_14 | 数据清洗语境。 |
+| multimodality | 多模态 | multimodal | lecture_17 | 模型正式名称不翻译。 |
+| KV cache | KV cache | KV cache | lecture_10 | 正式系统术语保留英文，解释为键值缓存。 |
+| latency | 延迟 | latency | lecture_10 | 与 throughput 成对出现。 |
+| throughput | 吞吐量 | throughput | lecture_10 | tokens/second 语境。 |
+| collective operation | 集合通信操作 | collective | lecture_07 | Broadcast/all-reduce 等操作名保留英文。 |
+| data curation | 数据策划 | curation | lecture_13 | 数据选择、清洗和组织的总称。 |
+| Jaccard similarity | Jaccard 相似度 | Jaccard | lecture_14 | 公式和集合符号保持原样。 |
+| MinHash | 最小哈希 | MinHash | lecture_14 | 算法名保留英文。 |
+| vision encoder | 视觉编码器 | encoder | lecture_17 | CLIP/SigLIP 等正式名称保留英文。 |
+| diffusion model | 扩散模型 | diffusion | lecture_17 | 图像生成语境。 |
diff --git a/docs/translation-inventory.md b/docs/translation-inventory.md
@@ -0,0 +1,28 @@
+# Translation Inventory
+
+Generated with Python AST scanning. Counts are a starting point for translation review, not a substitute for human judgment.
+
+| File | text(...) | image(...) | link(...) | verbatim | docstrings | comments | ordinary strings | course text strings | runtime/display strings | path/url/id strings | review blocks |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| lecture_01.py | 368 | 14 | 121 | 0 | 9 | 7 | 469 | 368 | 387 | 61 | 40 |
+| lecture_02.py | 210 | 11 | 14 | 0 | 5 | 54 | 275 | 210 | 226 | 44 | 21 |
+| lecture_06.py | 195 | 7 | 2 | 34 | 2 | 74 | 214 | 189 | 171 | 26 | 0 |
+| lecture_07.py | 104 | 7 | 6 | 0 | 7 | 74 | 187 | 104 | 139 | 36 | 47 |
+| lecture_10.py | 279 | 28 | 33 | 0 | 3 | 21 | 348 | 279 | 277 | 61 | 8 |
+| lecture_12.py | 220 | 43 | 46 | 0 | 0 | 0 | 329 | 220 | 210 | 101 | 8 |
+| lecture_13.py | 396 | 18 | 28 | 0 | 0 | 3 | 463 | 396 | 373 | 80 | 0 |
+| lecture_14.py | 249 | 18 | 27 | 7 | 0 | 6 | 341 | 249 | 235 | 81 | 11 |
+| lecture_17.py | 178 | 32 | 19 | 0 | 0 | 3 | 233 | 178 | 151 | 56 | 0 |
+
+## Classification Rules
+
+- Course text strings: first positional string passed to `text(...)`.
+- Runtime/display strings: non-path strings that may be visible in examples, prints, assertions, or generated output.
+- Path/url/id strings: URL, image path, file path, identifier-like, or command-like values that should usually remain unchanged.
+- Review blocks: strings that need human review before translation because their role is not obvious from AST context.
+
+## Translation Notes
+
+- `verbatim=True` blocks should keep the English ASCII table/output unchanged and receive a Chinese explanation underneath.
+- Strings that participate in assertions, parsing, control flow, or tokenizer examples should remain unchanged unless a separate explanatory line is added.
+- The generated trace JSON files are outputs and should be regenerated after source translation rather than edited directly.
diff --git a/docs/translation-review.md b/docs/translation-review.md
@@ -0,0 +1,28 @@
+# Translation Review
+
+This file tracks uncertain terminology, strings, or implementation choices that need human review.
+
+本文件记录需要人工复核的术语、句子和实现选择。
+
+## Open Items
+
+| Location | Item | Reason | Proposed handling |
+|---|---|---|---|
+| All lectures | Official model, dataset, benchmark, and paper names | 翻译后可能破坏检索和引用准确性 | 保留英文正式名称，必要时添加中文解释。 |
+| `verbatim=True` blocks | ASCII tables and example outputs | 直接插入中文会破坏对齐或改变示例输出 | 原块保持英文，在下方添加中文说明。 |
+| Tokenization examples | Example strings and token outputs | 字符串本身用于演示 tokenizer 行为 | 示例保持原样，只翻译周围解释。 |
+| Generated traces | `var/traces/*.json` | 生成产物，不应作为源头翻译 | 修改 Python 源文件后重新生成。 |
+| All translated lectures | Batch-generated Chinese text | 本轮优先完成全部可执行讲义覆盖，部分句子仍需人工润色以提高自然度 | 保留英文为准，逐讲人工校对中文表达。 |
+| `lecture_12.py` | `"\%"` SyntaxWarning | 原文件已有转义警告；本轮按要求未大范围修改，避免改变显示结果 | 如需修复，单独确认后改为 `"\\%"` 或 raw string。 |
+| Images | Embedded English labels | 本轮不修改图片文件 | 在后续 pass 为关键图片补充更细图下注释或标签对照。 |
+| `references.py` | `notes` Chinese render behavior | `Reference` 正式字段结构未知，不新增非原生字段 | 在 `notes` 中保留英文并紧跟中文说明。 |
+
+## Review Checklist
+
+- English source text is preserved.
+- Chinese text immediately follows the corresponding English.
+- Formulas, code, commands, URLs, and formal names remain intact.
+- Chinese explanations do not change assertions, control flow, or parser-sensitive strings.
+- Tables and code/output blocks keep their original alignment.
+- Static executable lecture `text(...)` calls have been converted to bilingual helpers.
+- `references.py` formal citation metadata remains unchanged.