Catholic Daily Readings

開源的天主教每日彌撒讀經 metadata service。

這個專案提供每日天主教禮儀讀經的結構化 metadata：日期、禮儀日、讀經類型、Lectionary Number、章節引用與可選讀經。它不儲存受版權保護的聖經正文，而是讓網站、API、CLI、App、Telegram bot、語音服務與不同語言社群，可以套用自己合法使用的譯本，產生適合自己的每日讀經。

為神做一些事，去填補這個世界應該要有的東西，讓神的話語更能遠傳。溫柔地對待這個世界。

🌐 English · 📖 繁體中文

---

✝️ 我們的使命

中文世界裡，沒有免費的、開放的天主教每日讀經系統。 我們相信天主的聖言應該被自由地傳遞。 這個項目，是對神的服侍。

「所以你們要去使萬民成為門徒。」 — 瑪竇福音 28:19

---

📐 數據分層架構

Layer 0 — Source Layer     原始 HTML 文件，凍存不動
Layer 1 — Processed Layer  citation_id JSON（無版權爭議）
Layer 2 — Applied Layer   各譯本完整章節顯示（譯本方處理）

版權原則：Layer 1 只儲存 citation_id（如 acts:2，公共遺產），不儲存有版權的經文本身。 詳見 wiki/Data-Layers.md。

---

📁 專案結構

catholic-daily-readings/
├── main.py                        # 入口腳本（Phase 1 MVP）
├── src/
│   ├── sources/
│   │   ├── usccb.py              # USCCB 讀經元數據
│   │   └── fhl.py                # 思高譯本 API
│   ├── core/
│   │   └── reader.py              # 數據組裝
│   └── cron/                      # 定時任務腳本
├── data/
│   ├── daily/                     # Layer 1 JSON（Processed Layer）
│   └── usccb-calendar/            # Layer 0 RAW 文件（原始 HTML）
├── scripts/
│   └── scrape_usccb_calendar.py  # USCCB 日曆 Scraper（Phase 2 核心工具）
└── wiki/                          # 研究與規劃文檔

---

🚀 快速開始

# 克隆專案
git clone https://github.com/westhong/catholic-daily-readings.git
cd catholic-daily-readings

# 安裝依賴
pip install -r requirements.txt

# 取得今日讀經
python main.py

# 啟動 Gospel metadata API
uvicorn src.api.main:app --host 0.0.0.0 --port 8000

---

🌐 Metadata API

這個 repo 有兩個 API runtime：

• Local / Docker: FastAPI at src/api/main.py
• Cloudflare Workers: TypeScript Worker at worker/

Public API 提供 citation-only Mass readings metadata。若沒有提供日期，會使用 America/Edmonton 的今天。

Endpoints:

GET /api/v1/readings
GET /api/v1/readings?date=YYYY-MM-DD
GET /api/v1/gospel
GET /api/v1/gospel?date=YYYY-MM-DD

FastAPI local:

uvicorn src.api.main:app --host 0.0.0.0 --port 8000
curl http://localhost:8000/api/v1/gospel
curl 'http://localhost:8000/api/v1/gospel?date=2026-04-19'

Cloudflare Worker local / deploy prep:

cd worker
npm install
npm test
npm run build          # wrangler dry-run build, no deploy
npm run dev            # local Worker dev server
# npm run deploy       # deploy later when ready

Full readings response example:

{
  "date": "2026-05-17",
  "timezone": "America/Edmonton",
  "source": "catholic-daily-readings",
  "records": [
    {
      "feast": "Seventh Sunday of Easter",
      "mass": "default",
      "lectionary_number": 59,
      "readings": {
        "first_reading": [{"citation": "Acts 1:12-14", "sources": ["USCCB"]}],
        "responsorial_psalm": [{"citation": "Psalm 27:1, 4, 7-8", "sources": ["USCCB"]}],
        "second_reading": [{"citation": "1 Peter 4:13-16", "sources": ["USCCB"]}],
        "alleluia": [{"citation": "John 14:18", "sources": ["USCCB"]}],
        "gospel": [{"citation": "John 17:1-11a", "sources": ["USCCB"]}]
      }
    }
  ]
}

Gospel-only response example:

{
  "date": "2026-04-19",
  "timezone": "America/Edmonton",
  "source": "catholic-daily-readings",
  "records": [
    {
      "feast": "Third Sunday of Easter",
      "mass": "default",
      "lectionary_number": 44,
      "gospels": [
        {"citation": "Luke 24:13-35", "sources": ["USCCB"]}
      ]
    }
  ]
}

---

📖 每日讀經格式（Phase 1 MVP）

每次獲取包含：

• Feast Day — 本日瞻禮名稱
• 讀經一 (First Reading) + 中文翻譯
• 答唱詠 (Responsorial Psalm) + 中文翻譯
• 福音 (Gospel) + 中文翻譯

所有中文譯文來自思高譯本，經文版權歸香港聖經公會所有。

---

🌱 未來願景

• 繁體中文每日靈修禱文（聖母玫瑰經、聖體聖事等）
• Layer 2 Applied Layer — 多語言譯本對接
• 祈禱時辰（Divine Office / Liturgy of the Hours）
• 每日推送（Email / Telegram）
• 印刷版 PDF 生成
• 語音版本（Text-to-Speech）

---

🤝 貢獻

歡迎貢獻！請參閱 wiki 了解專案規劃和當前進度。

如果你知道任何免費的天主教每日讀經來源（任何語言）、或有任何能令這個系統更豐富的想法，歡迎告訴我們：

📧 westhong@gmail.com

---

📜 授權與使用聲明

聖經經文

• 英文聖經經文：來自 New American Bible Revised Edition (NABRE)，版權 © Confraternity of Christian Doctrine (CCD)，Washington, DC。僅供私人研究使用。
• 中文聖經經文：來自律敦思高譯本，版權 © 香港聖經公會 / 信望愛資源中心。僅供私人研究使用。

讀經結構數據

讀經選擇與編排（Lectionary Selection）版權 © Confraternity of Christian Doctrine。僅供私人研究使用。

citation_id（Layer 1 核心欄位）

citation_id（如 acts:2、psalm:16）屬於公共遺產，無版權爭議。本專案僅儲存此類公共資料。

軟件

MIT — 自由使用，為主服務。

---

本專案旨在榮耀天主。所有聖經經文版權歸其各自持有者所有。

---

English

Catholic Daily Readings is an open metadata service for Catholic daily Mass readings.

It provides structured lectionary metadata — dates, liturgical days, reading types, lectionary numbers, citations, and optional readings — without storing copyrighted Bible text. Apps, APIs, CLI tools, bots, audio services, and language communities can use this metadata with their own licensed Bible translations to render the daily readings in the language, format, or voice their users prefer.

"Go, therefore, and make disciples of all nations." — Matthew 28:19

Motivation

There is no free, open-source Catholic daily readings system in Chinese. This project exists to change that — for the glory of God.

Data Architecture

Layer 0 — Source Layer     Raw HTML files, immutable
Layer 1 — Processed Layer  citation_id JSON (public domain, no copyright issues)
Layer 2 — Applied Layer    Full scripture display per translation (handled by translators)

citation_id (e.g., acts:2, psalm:16) is public domain. See wiki/Data-Layers.md.

Quick Start

git clone https://github.com/westhong/catholic-daily-readings.git
cd catholic-daily-readings
pip install requests beautifulsoup4
python main.py

Output: data/YYYY-MM-DD.json