LangMap

LangMap is an open-source, community-driven language map platform that collects phrases and expressions from languages around the world, showcases differences between languages, and provides a valuable resource for language enthusiasts.

LangMap 是一個開源、社區驅動的語言地圖平臺，致力於收集世界各地的語言短語和表達方式，展示不同語言之間的差異，爲語言愛好者提供有價值的學習資源。

→ 開始使用 langmap.io

中文 | English | 日本語 | Español | français | Deutsch | 한국어 | Português | Русский

主要功能

• 語言地圖 — 首頁熱力圖可視化展示各語言在全球的分布與語料豐富度（Leaflet + OpenStreetMap）
• 詞條搜索 — 支持按關鍵詞、語言、地域等多維度搜索和篩選詞句，查看詞句組內不同語言的翻譯對比
• 貢獻詞句 — 用戶可提交新詞句或批量跨語言提交同一語義的多語表達，系統自動歸入詞句組（Expression Group）
• 學習手冊（Handbook） — 基於 Markdown 的結構化學習筆記，嵌入詞句組後可動態切換目標語言，即時渲染翻譯
• 收藏集合 — 創建公開或私有的詞句收藏集，方便整理和分享
• 語言列表 — 按語言瀏覽所有詞條，查看各語言的語料統計
• 多語言界面 — 支持動態切換 UI 語言，社區可在線貢獻翻譯

詳細功能規劃請參見 PRD，技術架構請參見 系統架構設計。

技術棧

層級	技術
前端	Vue 3 + Vite + Tailwind CSS + vue-i18n + Leaflet
後端	Hono + TypeScript + Cloudflare Workers
數據庫	PostgreSQL + R2（對象存儲）
部署	Cloudflare Workers + Assets

參與開發

環境準備

• Node.js >= 22
• npm

前端開發

cd web
npm install
npm run dev

後端開發

cd backend
npm install
npm run dev

後端使用本地 Wrangler 執行，透過 DATABASE_URL 連接本地或測試 PostgreSQL；R2 使用本地模擬。翻譯透過 Worker 服務端的官方 openai SDK 呼叫 Cloudflare Workers AI OpenAI-compatible API。

本地全棧開發

./dev.sh

./dev.sh 啟動前端與 Worker，並檢查 backend/.dev.vars 或環境變數中的 DATABASE_URL。資料庫 schema／migration 由 scripts/postgres/manage.py 管理，不在 dev script 中重建或清除資料。

• ./dev.sh：啟動本地全棧服務。
• ./dev.sh --port=8790：將本地 API 綁到指定埠，前端仍代理到該埠。
• macOS 可用 Homebrew 安裝 PostgreSQL；程式與 importer 不依賴 Homebrew 或 psql。

翻譯需要在 backend/.dev.vars 中配置 Cloudflare 憑證（此檔案不提交）：

CLOUDFLARE_ACCOUNT_ID="your-account-id"
CLOUDFLARE_API_TOKEN="your-workers-ai-token"

本地 Wrangler 會自動將 .dev.vars 載入 Worker；未加 VITE_ 前綴的 token 不會透過 Vite 的 import.meta.env 暴露給瀏覽器。部署到 Cloudflare 時，帳號 ID 已配置在 backend/wrangler.jsonc， API token 請設定為 Worker secret：

cd backend
npx wrangler secret put CLOUDFLARE_API_TOKEN

完整構建

./build.sh

該腳本會安裝前端依賴、構建前端應用，並將產物複製到 backend/public 目錄。

數據庫配置

建立空 PostgreSQL database 後，以 DATABASE_URL 初始化 baseline：

python3 scripts/postgres/manage.py init
python3 scripts/postgres/manage.py migrate

macOS 可用 Homebrew 安裝並啟動本機 PostgreSQL：

brew install postgresql@17
brew services start postgresql@17
createdb langmap

本地 .dev.vars 最少需要：

DATABASE_URL="postgresql:///langmap"
SECRET_KEY="local-development-secret"

詞典 canonical CSV 先以 --check 驗證，再以同一 DATABASE_URL 執行 --apply；入口與欄位契約記錄於 scripts inventory。

貢獻指南

1. Fork 本倉庫
2. 創建功能分支（git checkout -b feat/your-feature）
3. 提交更改（git commit -m 'feat: add your feature'）
4. 推送分支（git push origin feat/your-feature）
5. 發起 Pull Request

部署

代碼推送到 main 分支後，Cloudflare 會自動構建並部署，無需手動操作。

如需手動部署：

./deploy.sh

此命令會先構建前端，再使用 Wrangler 將前端靜態資源（通過 Cloudflare Assets）和後端 API（通過 Cloudflare Workers）一併部署到 Cloudflare 邊緣網絡。

只驗證部署內容、不實際上線：

./deploy.sh --dry-run

後端未變更時可略過前端構建：

./deploy.sh --skip-build

文檔

• 業務需求文檔 (BRD)
• 產品需求文檔 (PRD)
• 系統架構設計
• API 文檔
• 功能模塊設計

License

Apache-2.0