指令碼與進階開發

命令列模式 (CLI)

💡 自動化指南：若您希望系統定期自動執行郵件截取，建議直接使用 TUI 的 Schedule 分頁（內建 pycron，時間到自動背景執行，無需設定外部排程器）。 但如果您希望透過其他系統從外部觸發執行，或是需要做測試與單次資料拋轉，CLI 則是您的最佳選擇。

單次任務或外部整合可直接使用 CLI 執行：

• uv tool 安裝模式：直接使用 mailslide ...
• 原始碼模式：使用 uv run mailslide ...

# 使用預設設定檔（原始碼模式）
uv run mailslide

# 使用預設設定檔（uv tool 安裝模式）
mailslide

# 指定自訂設定檔
uv run mailslide --config path/to/config.yaml

# 測試模式（僅讀取，不移動郵件）
uv run mailslide --dry-run

# 輸出結果至 JSON 檔案
uv run mailslide --output result.json

# 不移動郵件，僅擷取資料
uv run mailslide --no-move

Python import 遷移

如果你在程式碼中引入此套件，新的 import path 建議使用 mailslide：

from mailslide import load_config, LLMClient

最小可執行範例：

from pathlib import Path
from mailslide import load_config

config = load_config(Path("config/config.yaml"))
print(f"jobs: {len(config.get('jobs', []))}")

相容期內舊路徑 outlook_mail_extractor 仍可使用，但後續 major 版本將移除。

---

多語言 (gettext + Babel) 結構

本專案採用 key-based i18n：程式使用翻譯 key（例如 app.title）而非直接寫死文案。

• 執行期：gettext（若未編譯 catalog，會 fallback 到 outlook_mail_extractor/locales/*.yaml）
• 開發期：Babel 管理 po/mo

CLI 可用 --lang 暫時覆蓋語言：

uv run mailslide --lang en-US

或在 config/config.yaml 靜態設定：

ui_language: zh-TW

常用 Babel 指令

在專案根目錄執行：

# 抽取可翻譯字串到 POT
pybabel extract -F babel.cfg -o outlook_mail_extractor/locales/gettext/messages.pot .

# 初始化語言（首次）
pybabel init -i outlook_mail_extractor/locales/gettext/messages.pot -d outlook_mail_extractor/locales/gettext -D messages -l zh_TW

# 更新既有語言
pybabel update -i outlook_mail_extractor/locales/gettext/messages.pot -d outlook_mail_extractor/locales/gettext -D messages

# 編譯成 .mo 格式供程式讀取
pybabel compile -d outlook_mail_extractor/locales/gettext -D messages

（Windows 用戶也可直接使用腳本 ./scripts/i18n.ps1 all）