为 AWS Manila Community Day 的 Tagalog 卡片构建语法与发音增强流水线

Tagalog 学习应用已经有文章页面和句子卡片。下一个开发挑战是内容增强：在不手动编辑数百个重复 HTML 块的情况下，为每个额外示例加入更好的语法拆解和发音指南。Python 脚本展示了一种实用的批处理模式。

免责声明

用途：这个静态应用是用于语言练习和开发者分享的教育原型，帮助学习者为 AWS Manila Community Day 准备礼貌的 Tagalog 短语。

非商业用途：本项目没有付费功能、广告、注册要求或商业目的，仅用于学习、实验和社区准备。

不作保证：生成的语言内容可能包含错误。Tagalog 翻译、语法解释、发音指南和文化说明在生产使用前应由母语者复核。

范围：此应用不是 AWS 官方产品，不是官方翻译工具，也不能替代真人语言教学。它是一个带有实用学习内容的技术 Demo。

社区尊重：应用应避免刻板印象，并谨慎讲解礼貌用语。po、opo、kayo 和 ninyo 等词应被解释为表达尊重的工具，而不是装饰。

Demo

Paki-check po kung pumasok ang bayad.

语法拆解

• Paki-check: Filipino-English 请求短语，意思是“请检查”。
• po: 礼貌说话时使用的尊重标记。
• kung: 意思是“如果”或“是否”。
• pumasok: 在付款语境中表示“进入”或“到账”。
• bayad: 意思是“付款”。

发音指南

逐词发音可以读作：

pah-kee-chehk poh koong poo-mah-sohk ahng bah-yahd.

• Paki-check: pah-kee-chehk.
• po: poh.
• kung: koong.
• pumasok: poo-mah-sohk.
• bayad: bah-yahd.

内容快照

核心增强任务：

• 找到每个 div.extra-example 块
• 从 span 读取 Tagalog 句子
• 生成语法拆解列表项
• 生成发音指南文本和分块列表
• 替换 HTML 中的旧章节
• 写入更新后的文章文件
• 打印基本校验结果

目录

第 1 部分：按文章组使用批处理脚本

这一部分解释为什么增强工作要拆分到多个脚本中，而不是写成一个巨大的文件。

第 2 部分：把词汇表当作小型本地知识库

这一部分展示脚本如何使用字典条目，为初学者提供友好的语法含义和本地借词解释。

第 3 部分：从已知词和回退规则生成发音

这一部分解释发音映射、词元处理、元音回退规则，以及面向初学者的分块输出。

第 4 部分：用 BeautifulSoup 修补 HTML

这一部分展示一种代码模式：找到现有章节，并只替换目标标题之后的内容。

第 5 部分：验证增强后的输出

这一部分解释为什么脚本需要打印额外示例、发音短语、本地提示和语法拆解的数量。

第 1 部分：按文章组使用批处理脚本

目标

在不手动编辑每张卡片的情况下，改进 24 个文章页面中的语法和发音内容。

开发技能

关键技能是受控批处理。每个脚本负责一小组文章文件，并配有针对该组内容调优的词汇表。

files = [
    "article-22-manila-daily-home-laundry-bills-and-errands.html",
    "article-23-manila-daily-work-study-and-social-plans.html",
    "article-24-manila-daily-health-safety-weather-and-money.html",
]

这种模式比一个超大脚本更容易审查，因为每个批次都可以携带主题相关词汇。Community Day 页面需要 registration、workshop、badge、volunteer 等词；Manila Daily 页面需要 laundry、delivery、battery、cash、clinic、medicine 等词。

提示词

For each article group, update every extra example.
Keep the existing Tagalog sentence.
Replace the grammar breakdown with beginner-friendly word meanings.
Replace the pronunciation guide with word-by-word pronunciation.
Write an updated HTML file and print a summary.

结果

项目获得了一条可重复的增强工作流：

article group
  -> topic glossary
  -> visible Tagalog sentence
  -> grammar list
  -> pronunciation guide
  -> updated HTML
  -> sanity check

提示

• 当词汇随文章主题变化时，按主题拆分脚本。
• 保持文件列表明确，让审查者知道脚本作用范围。
• 在不同批次中使用相同的函数命名。
• 优先使用确定性输出，而不是运行时 AI 生成。
• 每个批次完成后打印摘要。

第 2 部分：把词汇表当作小型本地知识库

目标

把每个脚本变成一个小而可审查的语言辅助工具。

开发技能

脚本把字典当作本地知识库。像 po 或 saan 这样的词会得到稳定的初学者解释；未知词则回退到通用的本地用法说明。

defs = {
    "po": "Respect marker used for polite speech.",
    "saan": "Means where.",
    "workshop": "English loanword used locally; means workshop.",
    "badge": "English loanword used locally; means badge.",
}

def get_def(word):
    key = token_key(word)
    if key in defs:
        return defs[key]
    return f'English loanword or useful word used locally; means "{word}" in this context.'

为什么重要

这种方法不是完整的语法解析器，但对静态学习原型很有用。学习者能看到一致的含义，开发者也可以在某个解释需要改进时只更新一个字典条目。

示例

Sentence:
Saan po ang registration area?

Generated breakdown:
- Saan: Means where.
- po: Respect marker used for polite speech.
- ang: Focus marker placed before the main noun or idea.
- registration: English loanword used locally; means registration.
- area: English loanword or useful word used locally; means "area" in this context.

提示

• 保持定义简短。
• 如实解释借词，不要假装每个词都是纯 Tagalog。
• 使用适合初学者的表述。
• 当回退文本出现太频繁时，添加主题专属词汇条目。
• 把字典条目当作可审查内容。

第 3 部分：从已知词和回退规则生成发音

目标

即使不是每个词都在发音映射表中，也为每个额外示例提供可朗读的发音指南。

开发技能

脚本结合了两种策略：

Known word:
  use a curated pronunciation and optional syllable chunks.

Unknown word:
  use a simple vowel fallback so the learner still gets a readable guide.

代码模式

pron = {
    "salamat": ("sah-lah-maht", [("sa", "sah"), ("la", "lah"), ("mat", "maht")]),
    "kayo": ("kah-yoh", [("ka", "kah"), ("yo", "yoh")]),
    "bayad": ("bah-yahd", [("ba", "bah"), ("yad", "yahd")]),
}

vmap = {"a": "ah", "e": "eh", "i": "ee", "o": "oh", "u": "oo"}

def fallback_pron(word):
    output = []
    for character in word.lower():
        if character in vmap:
            output.append(vmap[character])
        elif character.isalpha():
            output.append(character)
    return "".join(output) or word

示例输出

Tagalog:
Uminom po kayo ng tubig dahil mainit.

Pronunciation:
oo-mee-nohm poh kah-yoh ngah too-beeg dah-heel mah-ee-neet.

Chunks:
- Uminom: oo-mee-nohm.
- po: poh.
- kayo: kah-yoh.
- tubig: too-beeg.
- dahil: dah-heel.
- mainit: mah-ee-neet.

提示

• 优先整理常见词。
• 让回退规则保持简单、透明。
• 谨慎保留缩写和技术词。
• 发音指南应足够用于练习，不必过度精确。
• 请母语者复核重要短语。

第 4 部分：用 BeautifulSoup 修补 HTML

目标

在不重写整个文章页面的情况下更新生成的 HTML。

开发技能

增强脚本使用 BeautifulSoup 解析页面，找到每个 div.extra-example，读取 Tagalog 的 span，然后替换特定标题之后的内容。

for fname in files:
    soup = BeautifulSoup(Path(fname).read_text(encoding="utf-8"), "html.parser")
    divs = soup.find_all("div", class_="extra-example")

    for div in divs:
        span = div.find("span", lang="tl")
        if not span:
            continue

        sentence = " ".join(span.get_text(" ", strip=True).split())
        replace_after_heading(div, "Grammatical Breakdown:", [make_breakdown_ul(soup, sentence)])
        replace_after_heading(div, "Pronunciation Guide:", make_pronunciation(soup, sentence))

辅助函数 replace_after_heading 很重要，因为它避免替换整张卡片。它只移除一个标题和下一个已知标题之间的旧内容。

def replace_after_heading(div, heading_text, new_nodes):
    heading = None
    for candidate in div.find_all("p", recursive=False):
        strong = candidate.find("strong")
        if strong and heading_text in strong.get_text():
            heading = candidate
            break

    if not heading:
        return False

    sibling = heading.find_next_sibling()
    while sibling:
        next_sibling = sibling.find_next_sibling()
        if sibling.name == "p":
            strong = sibling.find("strong")
            if strong and "Pronunciation Guide:" in strong.get_text():
                break
        sibling.extract()
        sibling = next_sibling

    last = heading
    for node in new_nodes:
        last.insert_after(node)
        last = node
    return True

提示

• 当结构很重要时，应解析 HTML，而不是盲目做字符串替换。
• 保持搜索范围足够窄。
• 保留学习者要练习的句子。
• 只替换生成的辅助章节。
• 测试高风险批次时，把输出写到单独文件中。

第 5 部分：验证增强后的输出

目标

证明批量更新确实触达了预期内容。

开发技能

脚本在写入文件后打印摘要行和基本校验结果。

print("Update summary:")
for source, out, total, updated, missing in summary:
    print(f"{source} -> {out}: extra_examples={total}, updated={updated}, missing={missing}")

print("Sanity check:")
for out in outputs:
    soup = BeautifulSoup(Path(out).read_text(encoding="utf-8"), "html.parser")
    divs = soup.find_all("div", class_="extra-example")
    phrase = sum(1 for div in divs if "It is pronounced word by word as:" in div.get_text())
    breakdown = sum(1 for div in divs if "Grammatical Breakdown:" in div.get_text())
    print(f"{out}: extra_examples={len(divs)}, pron_phrase={phrase}, has_breakdown={breakdown}")

结果

开发者可以把增强流水线解释为一个可衡量的过程，而不是一次手工清理。

Input:
article HTML files

Transformation:
grammar and pronunciation regeneration

Output:
updated HTML files

Evidence:
counts for extra examples, pronunciation phrases, and grammar breakdowns

提示

• 统计你实际修改的精确块数量。
• 打印缺失章节，而不是静默跳过。
• 让验证逻辑靠近脚本本身。
• 把生成的数量统计作为技术分享证据。
• 脚本通过后，目视检查几张更新后的卡片。

现场笔记 1：增强是产品层

背景：短语对很有用，但语法和发音会把它变成真正的学习卡片。

目标：在不改变句子卡片布局的情况下，加入可重复的学习支持。

提示词：从可见的 Tagalog 句子生成语法和发音。

结果：每个额外示例都对初学者更有帮助。

审查检查：生成的辅助内容是否解释了卡片上的真实句子？

现场笔记 2：批处理脚本应可审查

背景：一个脚本处理全部 24 篇文章会很大，也很难调优。

目标：让每个批次贴近自己的词汇领域。

提示词：每个脚本只处理三个文章文件。

结果：Community Day、Friendship 和 Manila Daily 内容都可以拥有更贴近本地语境的词汇表。

审查检查：审查者能否从文件列表和注释中理解词汇范围？

现场笔记 3：回退规则需要保持谦逊

背景：发音回退规则很有用，但它不是母语者保证。

目标：给学习者一个起点，同时让复核要求保持可见。

提示词：有整理好的发音时使用它；需要时使用简单回退。

结果：即使不是每个词都有完美发音条目，站点仍然有用。

审查检查：重要活动短语是否经过整理，而不是只依赖回退规则？

技术分享角度

对于开发者分享来说，这条增强流水线是实用内容工程的一个强示例：

HTML article files
      ->
BeautifulSoup parser
      ->
extra-example blocks
      ->
Tagalog sentence extraction
      ->
glossary definitions
      ->
pronunciation map and fallback
      ->
section replacement
      ->
updated HTML files
      ->
sanity checks

核心经验很简单：AI 辅助的学习内容仍然需要确定性工具。小脚本可以把生成页面转化为可审查的教育材料。

结语反思

语法和发音脚本展示了手工编辑与过度构建之间的实用中间路线。项目不需要数据库或语言引擎来改进每张卡片；它需要清晰的文章批次、主题词汇表、发音辅助函数、谨慎的 HTML 修补和验证输出。这样应用对学习者更有帮助，也更容易向开发者解释。