rust-analyzer-lsp

Immich 反向地理編碼 - 臺灣特化

[!IMPORTANT]

• 升級提醒：若您已部署本專案且媒體庫含有日本、南韓地區照片，請在更新至 v2.2.0 後執行「重新擷取照片中繼資料」，以套用最新的日本資料。
• 從 v2.2.0 起每個 release 都會附帶 update_data.sh，建議改用 release 內的腳本路徑以確保和釋出的資料一致；儘管倉庫內仍保留同名檔案，但以 release 版本為主。

繁體中文 | English

本專案為 Immich 提供專為臺灣使用者設計的反向地理編碼優化，根據使用者習慣提供自然且準確的地理資訊顯示。

目前支援：🇹🇼 臺灣 | 🇯🇵 日本 | 🇰🇷 南韓 | 🌏 其他地區中文化

設計理念

本專案以「臺灣使用者體驗」為核心，針對不同地區採用最適合的語言策略：

• 臺灣地區：使用 NLSC 圖資，解決國家與行政區名稱顯示問題
• 日本地區：使用国土数値情報ダウンロードサイト資料，保留日文原名（漢字+假名），符合臺灣使用者閱讀習慣
• 南韓地區：使用 admdongkor 專案資料，提供繁體中文翻譯，符合臺灣使用者閱讀習慣
• 其他地區：提供繁體中文翻譯，確保資訊可讀性（無對照譯名則回退至英文）

使用前後對比

目錄

• Immich 反向地理編碼 - 臺灣特化
  • 設計理念
    • 使用前後對比
  • 目錄
  • 支援地區與語言策略
  • 資料來源
  • 使用方式
    • 整合式部署（推薦，方便後續更新）
    • 手動部署
  • 指定特定版本
  • 行政區優化策略
    • 🇹🇼 臺灣地區優化
    • 🇯🇵 日本地區優化
    • 🇰🇷 南韓地區優化
  • 更新地理資料
    • 整合式部署
    • 手動部署
  • 開發者：本地資料處理
    • 1. 安裝依賴
    • 2. 提取原始地理資料
      • 臺灣資料提取
      • 日本資料提取
      • 南韓資料提取
    • 3. 完整資料處理流程
      • 註冊 LocationIQ API
      • 執行資料處理
  • 致謝
  • 授權條款

支援地區與語言策略

本專案根據臺灣使用者的閱讀習慣，對不同地區採用最合適的語言處理策略：

地區	語言策略	資料來源	說明
🇹🇼 臺灣	繁體中文（官方名稱）	NLSC 國土測繪中心	優化地理資料；解決國家與行政區顯示名稱錯誤的問題
🇯🇵 日本	日文原名（漢字+假名）	国土数値情報ダウンロードサイト	優化地理資料；以日文原名顯示
🇰🇷 南韓	繁體中文翻譯	admdongkor（官方行政區邊界）	優化地理資料；提供繁體中文翻譯
🌏 其他	繁體中文翻譯	自訂翻譯 → GeoNames 翻譯 → GeoNames 英文	優先使用臺灣慣用譯名，若無則使用 GeoNames 資料

為什麼日本保留日文？ 臺灣使用者普遍熟悉日文漢字與假名的組合，「横浜市」與「橫濱市」相比不容易造成辨識困難，「うるま市」亦不會影響普遍臺灣用戶的理解。

資料來源

本專案使用的地理數據主要來自以下來源：

1. GeoNames (geonames.org)
   • 授權: Creative Commons Attribution 4.0 International (CC-BY 4.0)
   • 用途: 作為全球地理位置的基礎數據庫
2. OpenStreetMap (透過 LocationIQ)
   • 授權: Open Database License (ODbL) 1.0
   • 用途: 透過 LocationIQ API 取得非臺灣、非日本地區的反向地理編碼資料
   • 聲明: Data © OpenStreetMap contributors, ODbL 1.0
3. 中華民國國土測繪中心 (NLSC)
   • 來源: 國土測繪中心開放資料平台
   • 資料集: 村(里)界 (TWD97經緯度), 版本 1140620
   • 授權: 政府資料開放授權條款-第1版
   • 用途: 作為臺灣地區村里界線及行政區名稱的主要數據源，確保資料的準確性與權威性
4. 国土数値情報ダウンロードサイト
   • 來源: 国土数値情報ダウンロードサービス
   • 資料集: 行政区域データ（世界測地系）
   • 授權: 日本政府公開資料
   • 用途: 作為日本地區行政區邊界與名稱的主要數據源
5. admdongkor
   • 來源: admdongkor
   • 資料集: 南韓官方行政區邊界資料（GeoJSON 格式）
   • 授權: MIT License
   • 用途: 作為南韓地區行政區邊界與名稱的主要數據源
6. 其他參考資料
   • 中華民國經濟部國際貿易署 & 中華民國外交部: 作為部分國家/地區中文譯名的參考來源

[!NOTE] 完整的資料來源聲明與授權資訊請參閱 NOTICE.md。

[!NOTE] 由於 Immich 的反向地理解析功能基於其載入的資料庫，並採用最近距離原則匹配地名，部分結果可能無法完全精確，或與預期不同。例如：

• 邊界附近的座標可能被判定為鄰近的行政區
• 某些小型島嶼或特殊地理位置可能無法精確對應

使用方式

本專案支援以下兩種部署方式：

1. 整合式部署（適用於 Immich 的 docker-compose 部署，可確保容器啟動時自動載入最新的臺灣特化資料）。

2. 手動部署（適用於自訂部署環境，可手動下載並配置特化資料）。

整合式部署（推薦，方便後續更新）

1. 修改 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 啟動服務。
   • 整合式部署也支援指定特定版本下載，詳情請參考 指定特定版本 章節。

2. 重啟 Immich
   執行以下命令以重啟 Immich：

   # 如果使用 docker-compose 部署
   docker compose down && docker compose up
   

   • 啟動後，檢查日誌中是否顯示 10000 geodata records imported 等類似訊息，確認 geodata 已成功更新。
   • 若未更新，請修改 geodata/geodata-date.txt 為一個更新的時間戳，確保其晚於 Immich 上次加載的時間。

3. 重新提取照片元數據
   登錄 Immich 管理後台，前往 系統管理 > 任務，點擊 提取元數據 > 全部，以觸發照片元數據的重新提取。完成後，所有照片的地理資訊將顯示為中文。
   新上傳的照片無需額外操作，即可直接支援中文搜尋。

手動部署