Immich 反向地理編碼 - 臺灣特化
[!IMPORTANT]
- 升級提醒：若您已部署本專案且媒體庫含有日本、南韓地區照片，請在更新至 v2.2.0 後執行「重新擷取照片中繼資料」，以套用最新的日本資料。
- 從 v2.2.0 起每個 release 都會附帶
update_data.sh，建議改用 release 內的腳本路徑以確保和釋出的資料一致；儘管倉庫內仍保留同名檔案，但以 release 版本為主。
繁體中文 | English
本專案為 Immich 提供專為臺灣使用者設計的反向地理編碼優化，根據使用者習慣提供自然且準確的地理資訊顯示。
目前支援：🇹🇼 臺灣 | 🇯🇵 日本 | 🇰🇷 南韓 | 🌏 其他地區中文化
設計理念
本專案以「臺灣使用者體驗」為核心，針對不同地區採用最適合的語言策略：
- 臺灣地區：使用 NLSC 圖資，解決國家與行政區名稱顯示問題
- 日本地區：使用国土数値情報ダウンロードサイト資料，保留日文原名（漢字+假名），符合臺灣使用者閱讀習慣
- 南韓地區：使用 admdongkor 專案資料，提供繁體中文翻譯，符合臺灣使用者閱讀習慣
- 其他地區：提供繁體中文翻譯，確保資訊可讀性（無對照譯名則回退至英文）
使用前後對比
目錄
支援地區與語言策略
本專案根據臺灣使用者的閱讀習慣，對不同地區採用最合適的語言處理策略：
| 地區 | 語言策略 | 資料來源 | 說明 |
|---|
| 🇹🇼 臺灣 | 繁體中文（官方名稱） | NLSC 國土測繪中心 | 優化地理資料；解決國家與行政區顯示名稱錯誤的問題 |
| 🇯🇵 日本 | 日文原名（漢字+假名） | 国土数値情報ダウンロードサイト | 優化地理資料；以日文原名顯示 |
| 🇰🇷 南韓 | 繁體中文翻譯 | admdongkor（官方行政區邊界） | 優化地理資料；提供繁體中文翻譯 |
| 🌏 其他 | 繁體中文翻譯 | 自訂翻譯 → GeoNames 翻譯 → GeoNames 英文 | 優先使用臺灣慣用譯名，若無則使用 GeoNames 資料 |
為什麼日本保留日文？
臺灣使用者普遍熟悉日文漢字與假名的組合，「横浜市」與「橫濱市」相比不容易造成辨識困難，「うるま市」亦不會影響普遍臺灣用戶的理解。
資料來源
本專案使用的地理數據主要來自以下來源：
- GeoNames (geonames.org)
- 授權: Creative Commons Attribution 4.0 International (CC-BY 4.0)
- 用途: 作為全球地理位置的基礎數據庫
- OpenStreetMap (透過 LocationIQ)
- 授權: Open Database License (ODbL) 1.0
- 用途: 透過 LocationIQ API 取得非臺灣、非日本地區的反向地理編碼資料
- 聲明: Data © OpenStreetMap contributors, ODbL 1.0
- 中華民國國土測繪中心 (NLSC)
- 來源: 國土測繪中心開放資料平台
- 資料集: 村(里)界 (TWD97經緯度), 版本 1140620
- 授權: 政府資料開放授權條款-第1版
- 用途: 作為臺灣地區村里界線及行政區名稱的主要數據源，確保資料的準確性與權威性
- 国土数値情報ダウンロードサイト
- admdongkor
- 來源: admdongkor
- 資料集: 南韓官方行政區邊界資料（GeoJSON 格式）
- 授權: MIT License
- 用途: 作為南韓地區行政區邊界與名稱的主要數據源
- 其他參考資料
- 中華民國經濟部國際貿易署 & 中華民國外交部: 作為部分國家/地區中文譯名的參考來源
[!NOTE]
完整的資料來源聲明與授權資訊請參閱 NOTICE.md。
[!NOTE]
由於 Immich 的反向地理解析功能基於其載入的資料庫，並採用最近距離原則匹配地名，部分結果可能無法完全精確，或與預期不同。例如：
- 邊界附近的座標可能被判定為鄰近的行政區
- 某些小型島嶼或特殊地理位置可能無法精確對應
使用方式
本專案支援以下兩種部署方式：
-
整合式部署（適用於 Immich 的 docker-compose 部署，可確保容器啟動時自動載入最新的臺灣特化資料）。
-
手動部署（適用於自訂部署環境，可手動下載並配置特化資料）。
整合式部署（推薦，方便後續更新）
-
修改 docker-compose.yml 配置
在 immich_server 服務內新增 entrypoint 設定，使容器啟動時自動下載最新地理資料：
services:
immich_server:
container_name: immich_server
# 其他配置省略
entrypoint: [ "tini", "--", "/bin/bash", "-c", "bash <(curl -sSL https://github.com/RxChi1d/immich-geodata-zh-tw/releases/latest/download/update_data.sh) --install && exec start.sh" ]
[!NOTE]
entrypoint 會在容器啟動時先執行本專案的 update_data.sh 腳本，自動下載並配置臺灣特化資料，隨後執行 Immich 伺服器的 start.sh 啟動服務。- 整合式部署也支援指定特定版本下載，詳情請參考 指定特定版本 章節。
-
重啟 Immich
執行以下命令以重啟 Immich：
# 如果使用 docker-compose 部署
docker compose down && docker compose up
- 啟動後，檢查日誌中是否顯示
10000 geodata records imported 等類似訊息，確認 geodata 已成功更新。
- 若未更新，請修改
geodata/geodata-date.txt 為一個更新的時間戳，確保其晚於 Immich 上次加載的時間。
-
重新提取照片元數據
登錄 Immich 管理後台，前往 系統管理 > 任務，點擊 提取元數據 > 全部，以觸發照片元數據的重新提取。完成後，所有照片的地理資訊將顯示為中文。
新上傳的照片無需額外操作，即可直接支援中文搜尋。
手動部署
