自动化HTML文本提取与翻译字典生成实践

在实际项目里，做前端国际化翻译字典提取时，最容易踩的第一个坑就是：到底哪些文本该提取，哪些该扔掉？直接用 innerText 或 textContent 一把梭抓取？这种方式太粗暴了，导航栏、页脚、广告脚本输出全都会被搂进来，导致噪声比信号还大。

提取HTML文本时，哪些内容该留、哪些该删

真正要进入翻译字典的，是用户可见且语义独立的文本节点。推荐的做法是先用 CSS 选择器划定范围，再逐节点过滤：

• 保留 h1–h6、p、li、dt / dd 中的纯文本
• 跳过 style、script、noscript、meta、link 标签及其后代
• 忽略含有 aria-hidden="true" 或 role="presentation" 的元素
• 对 input 和 textarea，只提取 placeholder 属性值；value 不提取——它属于运行时状态，不是界面文案

生成翻译键名时，为什么不能直接用文本内容做 key

“提交”“确定”“OK”这类短词在不同上下文里语义完全不同，直接当 key 会导致翻译错位；更致命的是，带空格、换行、HTML 实体（如 ）的文本无法稳定哈希或 JSON 序列化。

那么如何生成可靠且唯一、可复现的键呢？以下是几个实践要点：

• 用 DOM 路径 + 文本哈希组合，例如 "main-article-header-01#sha256:abc123"
• 路径部分使用 element.closest("article").dataset.id 或 element.parentElement.tagName 等轻量标识，避免依赖 class 名（ class 名容易变动）
• 对重复文本（如多个“查看详情”），加序号后缀："button-readmore-01"、"button-readmore-02"
• 跳过纯数字、纯 URL、base64 片段等机器生成内容——它们不应该进入翻译字典

Python 提取 + 生成 JSON 字典的最小可行代码

不需要重写轮子，BeautifulSoup 配合少量清洗逻辑就足够。关键不是功能全，而是输出稳定、可 diff、可增量更新。

看这个示例片段——注意 strip() 和 replace("\xa0", " ") 处理不间断空格：

from bs4 import BeautifulSoup
import hashlib
import json

def extract_translatable_texts(html_path):
    with open(html_path, encoding="utf-8") as f:
        soup = BeautifulSoup(f, "html.parser")

    texts = {}
    for tag in soup.find_all(["h1", "h2", "h3", "p", "li", "dt", "dd"]):
        text = tag.get_text(strip=True)
        if not text or len(text) < 2:  # 过滤单字符、空白
            continue
        text_clean = text.replace("\xa0", " ").strip()
        key = hashlib.sha256(text_clean.encode()).hexdigest()[:8]
        # 加上下文前缀防冲突
        full_key = f"{tag.name}-{key}"
        texts[full_key] = {"source": text_clean, "target": ""}
    return texts

保存为可编辑的 JSON，缩进 2，确保 git diff 友好：

with open("zh-CN.json", "w", encoding="utf-8") as f:
    json.dump(extract_translatable_texts("index.html"), f, indent=2, ensure_ascii=False)

后续维护时最容易被忽略的三个点

字典生成只是开始，真正卡住团队的是后续同步和冲突处理。以下是三个容易翻车的地方：

• HTML 结构微调（比如把 p 换成 div role="paragraph"）会导致 key 全变——必须配套维护 DOM 路径规则，不能只靠哈希
• 翻译人员填完 zh-CN.json 后，前端 JS 加载时若遇到缺失 key，应 fallback 到源文本，而不是留空或报错
• 每次重新提取，旧字典里的 "target" 字段要尽量保留，仅新增未出现的 key；用 dict.update() 而非覆盖写入