AWS Builder 文章

面向 AWS Manila Community Day 的 Tagalog 学习应用深度开发流程

这个 Tagalog 学习应用采用 file-first 的项目方式构建。开发流程不是从后端、数据库或框架开始，而是从结构化文章元数据、可复用句子库、卡片扩展逻辑、语言辅助函数、HTML 渲染、响应式 CSS、发布检查和最终打包开始。对技术分享来说，这是一个很强的模式，因为产品的每一部分都可以解释为一个可见的构建步骤。

Tagalog 学习应用文章系列

English 繁體中文 简体中文

这个 Tagalog 学习应用采用 file-first 的项目方式构建。开发流程不是从后端、数据库或框架开始，而是从结构化文章元数据、可复用句子库、卡片扩展逻辑、语言辅助函数、HTML 渲染、响应式 CSS、发布检查和最终打包开始。对技术分享来说，这是一个很强的模式，因为产品的每一部分都可以解释为一个可见的构建步骤。

Tagalog 学习应用生成器是一个很有用的技术分享示例，因为它结合了内容工程、静态站点生成、本地化意识、移动端 UI 思维和发布验证。代码规模不大，但其中的开发技能可以迁移到许多社区学习工具中。

免责声明

目的：这个静态应用是用于语言练习和技术分享的教育原型。它帮助学习者为 AWS Manila Community Day 准备礼貌的 Tagalog 短语，同时向 builders 展示生成器如何工作。

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

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

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

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

审核要求：语言内容，尤其是文化说明和礼貌 Tagalog 解释，在生产使用前应由母语者审核。

Demo

Lagyan po ng yelo.

语法拆解

  • Lagyan：表示把某物放到或加到某个地方或物品上。
  • po：用于表达尊重的礼貌标记。
  • ng：连接词或标记，常用于宾语前。
  • yelo：表示“冰”。

发音指南

逐词发音如下：
lahg-yahn poh ngah yeh-loh.

  • Lagyan：lahg-yahn。
  • po：poh。
  • ng：ngah。
  • yelo：yeh-loh。
    点单或向摊主提出请求时，语气保持简短、柔和。

内容快照

自然 Tagalog：Lagyan po ng yelo.
礼貌 Tagalog：Lagyan po ng yelo.
补充示例 1：Sa palengke, lagyan po ng yelo.
补充示例 2：Ganito na lang, lagyan po ng yelo.
相关市场示例：Konting asukal lang po.

目录

第 1 部分：把内容视为产品契约

本节说明文章元数据、分类、slug 和摘要如何成为静态站点的第一层 API。

第 2 部分：把句子库作为可复用源数据

本节展示基础句子元组如何支持自然 Tagalog、礼貌 Tagalog、友好的 Filipino-English、有趣的 Filipino-English 和语气标签。

第 3 部分：把小输入扩展成更大的学习卡组

本节说明如何通过将基础短语与语境变体结合，让一个小型句子库为每篇文章生成 40 张卡片。

第 4 部分：从结构化数据渲染静态 HTML

本节说明生成器如何把内容对象转换为文章页面、导航列表、句子卡片和落地页。

第 5 部分：打包并验证 Demo

本节深入介绍 zip 生成、摘要字数校正、移动端 CSS 检查、卡片数量检查和适合发布的验证。

第 6 部分：用普通数据建模学习产品

本节说明项目如何用普通 Python 数据结构建模文章、句子库、语境、示例、语法和发音。

第 7 部分：确定性地生成大型学习集

本节展示确定性扩展如何在保持一致语气和结构的同时创建大量学习卡片。

第 8 部分：添加语法、示例和发音辅助函数

本节深入介绍语法拆解、示例选择和发音指南生成。

第 9 部分：构建响应式静态学习界面

本节说明生成器如何构建基于文章的深色模式、响应式学习界面。

第 10 部分：让 QA 和发布成为 Demo 的一部分

本节说明打包与检查如何把生成式原型变成可分享的技术 demo。

第 1 部分：把内容视为产品契约

目标

在编写 UI 逻辑前创建可预测的内容契约。生成器定义十篇文章，并包含 id、slug、title、category 和 summary。这样每篇文章都可以被寻址、链接和渲染。

开发技能

这里的开发技能是 schema-first 思维。即使没有数据库，文章列表也像 API 一样工作。后续每个步骤都依赖稳定的键：

{
  "id": 1,
  "slug": "community-greetings-introductions",
  "title": "Community Day: Greetings and Respectful Introductions",
  "category": "Community Day",
  "summary": "Practice polite greetings..."
}

Prompt

创建一个包含 24 个文章页的静态学习站点。
每篇文章需要：
- id
- slug
- title
- category
- 20 词摘要
- 40 张句子卡片

使用 11 篇 Community Day 文章、8 篇 Friendship 文章和 5 篇 Manila Daily 文章。

结果

生成器可以生成可预测的文件名，例如：

article-1-community-greetings-introductions.html
article-3-community-workshops-learning.html
article-5-community-volunteers-time-goodbye.html

这种命名模式适合技术分享，因为文件名本身就说明了路由、文章编号和主题。

提示

  • 使用 slug 而不是原始标题作为文件名。
  • 文章 ID 保持数字形式，方便排序。
  • 分类保持明确，便于 UI 徽标展示。
  • 单独验证摘要，不要与正文混在一起。
  • 元数据应足够可读，即使不运行应用也能审核。

第 2 部分：把句子库作为可复用源数据

目标

先把学习内容保存为紧凑的源数据，再扩展成完整卡片。每个句子元组携带六个有用字段：

英文输入
自然 Tagalog
礼貌 Tagalog
友好的 Filipino-English
有趣的 Filipino-English
语气

开发技能

这里的技能是内容规范化。与其手写 400 张完整 HTML 卡片，不如使用紧凑元组作为源数据，再让渲染函数补充语法、示例、文化语境和发音。

Prompt

创建适合活动现场使用的基础句子库。
每个句子提供：
- 英文输入
- 自然 Tagalog
- 礼貌 Tagalog
- 友好的 Filipino-English
- 有趣的 Filipino-English
- 语气

包含问候、指路、工作坊、交流、志愿者、等待时间和道别。

Demo 示例

English：Sit for a moment if you feel dizzy.
自然 Tagalog：Umupo ka sandali kung nahihilo ka.
礼貌 Tagalog：Umupo po kayo sandali kung nahihilo kayo.
友好的 Filipino-English：Sit muna po kung dizzy.
有趣的 Filipino-English：Umupo muna, easy lang all right.
语气：关心健康建议

English：Thank you for being my safe friend.
自然 Tagalog：Salamat sa pagiging ligtas kong kaibigan.
礼貌 Tagalog：Salamat sa pagiging ligtas ko pong kaibigan.
友好的 Filipino-English：Thank you po for being my safe friend.
有趣的 Filipino-English：Safe friend ka, thank you all right.
语气：温柔的友谊关怀

结果

内容模型同时支持实用的活动现场表达和语气教学。学习者可以在尊重语气的句子旁边看到随意和有趣的变体。

提示

  • 先放自然 Tagalog，再放有趣版本。
  • 在需要表达尊重的场景使用 po、kayo 和 ninyo。
  • 明确标注有趣表达属于非正式语气。
  • 尽早添加语气标签。
  • 构建足够多的句子分类，用来测试完整活动旅程。

第 3 部分：把小输入扩展成更大的学习卡组

目标

通过把每个基础句子与四个语境变体组合，将 10 个基础句子扩展为每篇文章 40 张卡片。Community Day 语境包括早晨签到、工作坊开始、遇到志愿者和 session 后使用。

开发技能

这里的技能是受控扩展。生成器在放大内容时不让输出变得随机。每张生成卡片仍然遵循同一个句子卡模板。

Prompt

把每篇文章从 10 个基础句子扩展为 40 张学习卡片。
每个基础句子使用四个语境变体。
句子文本保持清晰，把场景细节放在背景语境中。

实现模式

def expand(base, article_id):
    contexts = community_contexts if article_id <= 5 else friendship_contexts
    cards = []
    for sentence in base:
        for context in contexts:
            cards.append({
                "num": len(cards) + 1,
                "background": "Use this sentence in this context...",
                "english": sentence[0],
                "natural": sentence[1],
                "polite": sentence[2],
                "friendly": sentence[3],
                "playful": sentence[4],
                "tone": sentence[5]
            })
    return cards[:40]

结果

站点现在可以扩展到 960 张句子卡片，同时不丢失结构。这实际展示了如何把 AI 辅助内容塑造成确定性的产品。

提示

  • 扩展语境，而不是随机改写措辞。
  • 保持原句稳定，方便记忆。
  • 使用确定性的卡片编号。
  • 用 [:40] 限制生成卡片，防止溢出。
  • 扩展后从每个分类抽样审核。

第 4 部分：从结构化数据渲染静态 HTML

目标

用同一个 HTML 函数渲染每个文章页。生成器创建文章导航、hero 内容、元数据徽标、句子卡片、上一篇/下一篇链接和移动端控件。

开发技能

这里的技能是不依赖框架的模板渲染。Python 字符串模板、HTML escaping 和小型辅助函数已经足以构建完整静态站点。

Prompt

为每篇文章生成一个 HTML 页面。
桌面端 UI：
- 左侧文章列表
- 右侧文章内容

移动端 UI：
- 内容优先
- 打开文章列表按钮
- 抽屉式文章列表

使用深色模式和响应式 CSS。

渲染职责

page_html(article)
  -> 当前导航状态
  -> hero 区域
  -> 句子卡片
  -> 上一篇和下一篇链接
  -> 移动端抽屉按钮

sentence_card_html(card, article)
  -> 背景语境
  -> 英文输入
  -> 自然 Tagalog
  -> 礼貌 Tagalog
  -> 友好的 Filipino-English
  -> 有趣的 Filipino-English
  -> 文化语境
  -> 语法
  -> 示例
  -> 发音

结果

HTML 输出保持一致，因为每篇文章都使用同一个渲染器。这避免了 demo 中常见的问题：各页面慢慢漂移成不同布局。

提示

  • 对生成内容使用 html.escape()。
  • 用 CSS 变量管理深色模式颜色。
  • 所有页面使用同一个导航渲染器。
  • 添加语义化文章卡片。
  • JavaScript 保持小规模，仅用于移动端抽屉。

第 5 部分：打包并验证 Demo

目标

分享前创建 zip 文件并运行一致性检查。打包脚本会把摘要更新为正好 20 个词，重写 HTML 文件，创建 tagalog_static_html_site.zip，并打印验证结果。

开发技能

这里的技能是发布卫生。静态站点仍然需要发布流水线：修补、打包、验证和审核。

Prompt

发布前验证：
- 每篇文章都有 40 张句子卡片
- 摘要正好 20 个词
- 移动端 CSS 存在
- 输出不包含禁止的内部引用
- zip 文件包含全部 HTML 页面

验证模式

checks[p.name] = {
    "sentence_cards": text.count('class="sentence-card"'),
    "mentions_readme": bool(re.search(r"readme", text, re.I)),
    "has_mobile_css": "@media (max-width: 860px)" in text,
}

Demo 锚点回归集

每当生成站点发生变化时，使用这些最新 HTML 示例作为回归集：

Tagalog：Magpahinga muna tayo sa lilim.
English：Let us rest in the shade first.
检查：健康/安全语境、自然对话句，以及没有重复的 Extra Example 模式。

Tagalog：Umupo ka sandali kung nahihilo ka.
English：Sit for a moment if you feel dizzy.
检查：关怀建议、适合初学者的措辞，以及实用的 Manila 日常使用场景。

Tagalog：Paki-check po kung pumasok ang bayad.
English：Please check if the payment came in.
检查：礼貌请求、付款语境，以及清晰的 Extra Example 措辞。

结果

最终步骤证明预期内容确实存在，因此 demo 更适合分享。这对技术分享尤其重要，因为观众看到的不只是 demo，也能看到背后的构建纪律。

提示

  • 每次发布构建后打印 JSON 检查。
  • 把字数要求当作可测试约束。
  • 只打包你希望分发的确切文件。
  • 对文件排序，让包内容可预测。
  • 修补后再运行检查，而不是修补前。

第 6 部分：用普通数据建模学习产品

目标

用易于检查、修改和渲染的简单 Python 结构表示一个学习产品。

开发技能

关键技能是把字典和元组当作轻量内容数据库使用。项目使用：

articles：文章元数据列表
community_sets：活动短语库
friendship_sets：情感短语库
community_contexts：实用活动场景
friendship_contexts：情感表达场景
pron_map：发音提示

Prompt

把学习应用内容建模为结构化 Python 数据。
使用文章元数据生成导航。
使用句子库生成学习卡片。
使用语境数组扩展每个基础句子。
使用辅助映射生成发音和语法。

为什么重要

这种方法让系统更易解释。在技术分享 session 中，builder 可以指向一个数据结构，说明它如何变成导航、文章内容和句子卡片。

提示

  • 将文章元数据与句子内容分开。
  • 将活动分类与友谊或诗意分类分开。
  • 只有字段顺序稳定时才使用元组。
  • 当键需要自解释时使用字典。
  • 如果非 Python 用户需要编辑，可后续升级为 JSON。

第 7 部分：确定性地生成大型学习集

目标

在不失去一致性的前提下生成大型学习集。

开发技能

这里的技能是确定性生成。应用不会在运行时要求 AI 自由发明每个最终页面。它先定义基础数据，扩展数据，再渲染静态输出。

Prompt

使用确定性生成，而不是手工复制。
对每个基础句子生成四张带语境的卡片。
保持输出顺序稳定。
自动分配卡片编号。
每篇文章正好返回 40 张卡片。

实现概念

for base_sentence in base_sentences:
    for context in contexts:
        create_card(base_sentence, context)

结果

应用可以增长，同时仍然可审核。如果某个翻译需要改进，开发者只需编辑一次基础句子并重新生成站点。

提示

  • 源短语只保存一次。
  • 自动生成重复布局。
  • 保持卡片编号确定。
  • 已发布的学习内容避免随机化。
  • 使用构建检查确认精确数量。

第 8 部分：添加语法、示例和发音辅助函数

目标

通过生成语法注释、补充示例和发音提示，让学习价值超越翻译本身。

开发技能

这里的技能是基于规则的增强。生成器会检查英文输入和自然 Tagalog，决定附加哪类语法说明。

Prompt

创建辅助函数，根据句子意图添加语法和示例。
如果句子表达感谢，解释 Salamat、po 和 sa。
如果句子询问地点，解释 Saan、po 和 ang。
如果句子是礼貌请求，解释 Puwede、Paki-、po 和 ba。
如果句子涉及等待，解释 Hintayin、Papunta、Pasensya、na 和 po。

辅助函数行为示例

句子：Let us rest in the shade first.
语法：
- Salamat：谢谢
- po：礼貌标记
- sa：根据语境可表示 for、in、at 或 to

句子：Sit for a moment if you feel dizzy.
语法：
- Puwede / Paki-：可以、能否或请
- po：礼貌标记
- ba：疑问标记

Demo 示例

辅助系统会反复使用适合活动现场的示例：

Tagalog：Magpahinga muna tayo sa lilim.
English：Let us rest in the shade first.

Tagalog：Umupo ka sandali kung nahihilo ka.
English：Sit for a moment if you feel dizzy.

Tagalog：Paki-check po kung pumasok ang bayad.
English：Please check if the payment came in.

结果

应用教授的是模式，而不只是短语对。这对技术 demo 更有价值，因为它展示了简单规则层如何改进学习内容。

提示

  • 保持辅助规则透明。
  • 为初学者使用简单的语法说明。
  • 不要夸大语言学准确性。
  • 为语法注释加入母语者审核。
  • 让辅助函数创造一致性，而不是成为最终权威。

第 9 部分：构建响应式静态学习界面

目标

生成一个在桌面端和移动端都可用的静态站点。

开发技能

这里的 UI 技能是响应式静态组合。应用使用：

桌面端：侧边栏导航 + 文章内容
移动端：内容优先 + 文章抽屉按钮
深色模式：CSS 变量和可读对比度
卡片：重复的 sentence-card 组件
导航：当前文章链接和上一篇/下一篇链接

Prompt

创建一个深色模式静态 HTML 学习站点。
桌面端布局应左侧显示文章导航，右侧显示内容。
移动端布局应先显示内容，并提供“打开文章列表”按钮。
使用语义化卡片，并让 UI 适合长篇语言学习内容阅读。

CSS 概念

:root {
  --bg: #090b10;
  --text: #e5e7eb;
  --muted: #9ca3af;
  --brand: #38bdf8;
  --border: #273449;
}

.layout {
  display: grid;
  grid-template-columns: 360px 1fr;
}

@media (max-width: 860px) {
  .layout {
    display: flex;
    flex-direction: column;
  }

  .content {
    order: 1;
  }

  .mobile-menu-button {
    display: block;
  }
}

结果

应用可以作为纯浏览器学习工具使用。对 AWS Manila Community Day 准备来说，这很重要，因为学习者可能在出行、等待或 session 前复习时用手机练习。

提示

  • 移动端优先显示学习内容，再显示导航。
  • 使用较大的触控目标。
  • 让语法部分易于快速浏览。
  • 谨慎使用深色模式，不要只当装饰。
  • JavaScript 保持最小。

第 10 部分：让 QA 和发布成为 Demo 的一部分

目标

让生成的站点可靠到足以分享。

开发技能

这里的技能是自动一致性检查。打包脚本会检查：

句子卡片数量
移动端 CSS 标记
禁止的内部引用提及
摘要字数
zip 创建

Prompt

创建一个发布脚本：
- 将文章摘要修补为正好 20 个词
- 重写所有 HTML 文件
- 将文件打包为 zip
- 为每个页面打印 JSON 检查结果

发布模式

files = list(Path('.').glob('*.html'))

for page in files:
    text = page.read_text(encoding='utf-8')
    # patch content
    page.write_text(text, encoding='utf-8')

with zipfile.ZipFile(zip_name, 'w', zipfile.ZIP_DEFLATED) as z:
    for page in sorted(files):
        z.write(page.name)

结果

最终产物不只是一组生成页面，而是经过检查和打包的构建结果。在技术分享 session 中，这种区别很重要，因为它展示了专业的发布思维。

提示

  • 以 JSON 打印验证输出。
  • 每次修补后检查要求。
  • 只打包预期文件。
  • 保持发布脚本小而可审计。
  • 把检查结果作为技术分享中的讲解点。

现场笔记

UI 之前的内容契约

背景：应用现在需要 24 篇文章、960 张卡片、摘要、分类、语气变体和 2,680 行唯一的 Extra Example。

目标：防止手写页面发生漂移。

Prompt：先定义文章元数据和句子元组，再渲染 HTML。

结果：同一个生成器可以渲染整个站点。

审核检查：每篇文章是否都能从 id、slug、title、category、summary 和 cards 渲染出来？

受控扩展

背景：为每篇文章手写 40 张唯一卡片既慢又不一致。

目标：安全地把 10 个基础句子扩展成 40 张卡片。

Prompt：将基础句子与四个语境组合，同时保持句子稳定。

结果：每篇文章达到所需卡片数量，结构不随机。

审核检查：每篇文章是否正好显示 40 张卡片？

把发布脚本作为 QA

背景：第一次生成可能遗漏字数要求或发布规则。

目标：打包前修补并验证最终输出。

Prompt：替换摘要、压缩文件并打印检查结果。

结果：最终构建包含 20 词摘要、移动端 CSS，并且没有禁止的内部引用。

审核检查：构建日志是否显示摘要数量、移动端 CSS 和卡片数量？

普通 Python 也可以是静态站点生成器

背景：应用需要许多页面，但不需要运行时服务端逻辑。

目标：一次性生成 HTML，并可部署到任何地方。

Prompt：使用 Python 从结构化内容创建文章页和 index 页面。

结果：站点变得容易打包、检查和分享。

审核检查：站点是否无需后端即可打开？

辅助函数就是产品决策

背景：语法拆解和发音不是原始数据，它们会塑造学习者理解。

目标：一致地编码适合初学者的解释。

Prompt：为发音、语法拆解、示例和相关模式添加辅助函数。

结果：每张卡片都获得学习支持，无需反复手写同样说明。

审核检查：辅助说明是否匹配句子意图？

QA 是叙事的一部分

背景：如果数量或移动端规则出错，生成式 demo 可能静默失败。

目标：让验证可见。

Prompt：打印卡片数量、移动端 CSS 和禁止词检查。

结果：构建输出成为 demo 满足要求的证据。

审核检查：最终 JSON 检查是否显示预期值？

技术分享应展示流程

背景：当 builders 看到文件、prompt、schema 和检查如何连接时，学习会更快。

目标：把项目呈现为可重复的构建模式。

Prompt：解释从数据模型到生成页面再到发布 zip 的流程。

结果：这场分享的价值超越这个 Tagalog 应用本身。

审核检查：另一个 builder 是否能把同样流程复用于另一个学习主题？

收尾反思

这个开发流程对技术分享有价值，因为它展示了从内容想法到可分发静态站点的完整路径。重要的经验不只是如何写 HTML 或 Python，而是如何设计内容契约、生成一致页面、验证要求，并有信心地打包结果。Tagalog 学习应用背后的工程技能，是把一个文化学习目标转化为可重复的内容流水线，让数据建模、确定性生成、辅助函数、响应式渲染和发布验证协同工作。