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

[!IMPORTANT]

升級提醒：v3.1.0 整合國教院官方譯名優化全球地名翻譯，並新增印尼圖資（繁體中文在地化）；v3.0.0 新增泰國圖資。若您已部署本專案，請在更新後執行「重新擷取照片中繼資料」，以套用最新資料。

繁體中文 | English

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

目前支援：🇹🇼 臺灣 | 🇯🇵 日本 | 🇰🇷 南韓 | 🇹🇭 泰國 | 🇮🇩 印尼 | 🌏 其他地區中文化

設計理念

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

臺灣地區：使用 NLSC 圖資，解決國家與行政區名稱顯示問題
日本地區：使用国土数値情報ダウンロードサイト資料，保留日文原名（漢字+假名），符合臺灣使用者閱讀習慣
南韓地區：使用 admdongkor 專案資料，提供繁體中文翻譯，符合臺灣使用者閱讀習慣
泰國地區：使用 COD-AB 官方邊界資料，提供 Admin1/Admin2 繁中翻譯，並以官方英文與泰文作為 fallback
印尼地區：使用 BIG（印尼地理空間資訊局）官方村級圖資，提供 Admin1/Admin2 繁中翻譯，缺中文標籤時回退 BIG 官方印尼文
其他地區：優先採用國家教育研究院《外國地名譯名》的官方臺灣譯名補洞與升級，其次使用 GeoNames 翻譯，確保資訊可讀性（無對照譯名則回退至英文）

使用前後對比

支援地區與語言策略

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

地區	語言策略	資料來源	說明
🇹🇼 臺灣	繁體中文（官方名稱）	NLSC 國土測繪中心	優化地理資料；解決國家與行政區顯示名稱錯誤的問題
🇯🇵 日本	日文原名（漢字+假名）	国土数値情報ダウンロードサイト	優化地理資料；以日文原名顯示
🇰🇷 南韓	繁體中文翻譯	admdongkor（官方行政區邊界）	優化地理資料；提供繁體中文翻譯
🇹🇭 泰國	繁體中文翻譯（官方英文 / 泰文 fallback）	COD-AB Thailand	優化地理資料；以官方行政區邊界計算行政區中心點
🇮🇩 印尼	繁體中文翻譯（BIG 官方印尼文 fallback）	BIG（Badan Informasi Geospasial）	優化地理資料；以村級邊界計算行政區中心點，涵蓋 38 省
🌏 其他	繁體中文翻譯	國教院官方譯名 → 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 格式）
- 授權: 無額外限制（作者建議標示出處，詳見 NOTICE.md）
- 用途: 作為南韓地區行政區邊界與名稱的主要數據源
Thailand COD-AB
- 來源: HDX Thailand Subnational Administrative Boundaries
- 資料集: Thailand administrative level 0-3 boundaries (COD-AB)
- 授權: Creative Commons Attribution for Intergovernmental Organisations (CC BY-IGO)
- 用途: 作為泰國地區行政區邊界與名稱的主要數據源
印尼地理空間資訊局（BIG，Badan Informasi Geospasial）
- 來源: BIG 官方 ArcGIS REST FeatureServer（desa 村級圖徵服務）
- 資料集: 印尼行政區 desa（村級）邊界，版本 TASWIL20230928，含 38 省全量資料
- 授權: 印尼官方公開地理資料（本專案僅作衍生加工輸入，不散布原始向量圖資）
- 用途: 作為印尼地區行政區邊界與名稱的主要數據源
國家教育研究院《外國地名譯名》
- 來源: 政府資料開放平臺 dataset 15211
- 授權: 政府資料開放授權條款-第1版
- 用途: 全球非 handler 地區的官方臺灣譯名補洞與覆寫
其他參考資料
- 中華民國經濟部國際貿易署 & 中華民國外交部: 作為部分國家/地區中文譯名的參考來源

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

手動部署

修改 docker-compose.yml 配置
在 volumes 內新增以下映射（請依據實際環境調整路徑）：
```
volumes:
  - /mnt/user/appdata/immich/geodata:/build/geodata:ro
  - /mnt/user/appdata/immich/i18n-iso-countries/langs:/usr/src/app/server/node_modules/i18n-iso-countries/langs:ro
```
[!NOTE] 若使用 Immich < 1.136.0 版本，請將第二行改為：
/mnt/user/appdata/immich/i18n-iso-countries/langs:/usr/src/app/node_modules/i18n-iso-countries/langs:ro
下載臺灣特化資料
提供以下兩種下載方式：

(1) 自動下載
參考本專案中的 update_data.sh 腳本，修改 DOWNLOAD_DIR 為存放 geodata 和 i18n-iso-countries 的資料夾路徑，並執行腳本：
```
   bash update_data.sh
```
[!NOTE]
- 手動部署也支援指定特定版本下載，詳情請參考指定特定版本章節。
- UnRAID 使用者可以通過 User Scripts 插件執行腳本。
(2) 手動下載
前往 Release 頁面查找所需的版本，下載對應的 release.tar.gz 或 release.zip，並將其解壓縮至指定位置。
重啟 Immich 和重新提取照片元數據
與整合式部署的步驟 2、3 相同。

指定特定版本

在某些情況下（例如最新的 release 出現問題），你可能需要下載或回滾到特定的 release 版本。本專案的更新腳本支援透過 --tag 參數來指定要下載的 release tag。

如何找到可用的 Tag？ 請前往本專案的 Releases 頁面查看所有可用的 release tag 名稱（例如 v2.2.4, nightly 等）。

使用範例：

整合式部署 (docker-compose.yml 中的 entrypoint) 在 entrypoint 的指令後面加上 --tag <tag_name>：
```
entrypoint: [ "tini", "--", "/bin/bash", "-c", "bash <(curl -sSL https://github.com/RxChi1d/immich-geodata-zh-tw/releases/download/<tag_name>/update_data.sh) --install --tag <tag_name> && exec start.sh" ] 
```
將 <tag_name> 分別替換為你想要下載的具體 tag 名稱。如果省略 --tag，則預設下載最新的 release (latest)。
手動部署 (update_data.sh) 執行腳本時加上 --tag <tag_name>：
```
bash update_data.sh --tag <tag_name>
```
將 <tag_name> 替換為你想要下載的具體 tag 名稱。如果省略 --tag，則預設下載最新的 release (latest)。

[!NOTE] 腳本會先驗證指定的 tag 是否存在於 GitHub Releases，如果 tag 無效則會提示錯誤並終止執行，因此請在執行前確保 tag 有效。

行政區優化策略

🇹🇼 臺灣地區優化

官方圖資為核心：使用 NLSC 村(里)界圖資，確保資料權威性
優化國家與行政區名稱：解決 Immich 原生資料中「臺灣」顯示為「中國臺灣省」且缺失多數縣市名稱的問題
行政區層級優化：優化 Admin1（直轄市/省轄縣市）與 cities500（地名資料）

📖 詳細的臺灣資料處理邏輯請參閱臺灣行政區處理文檔

🇯🇵 日本地區優化

保留日文原名：維持漢字+假名組合（如「静岡県」而非「靜岡縣」）
行政區細分處理：普通市、特別區、政令指定都市、東京都特別區部等均有適當處理
郡轄町村智慧處理：自動判斷是否需要郡名前綴，避免同名衝突

📖 詳細的日本行政區處理邏輯請參閱日本行政區處理文檔

🇰🇷 南韓地區優化

繁體中文翻譯：從 admdongkor 專案提取官方行政區邊界並自動翻譯為繁體中文
行政區命名優化：廣域市統一加「市」字（首爾市、釜山市、大邱市等）
特殊行政區處理：濟州道與濟州市區分、世宗市採用業界通用譯名
行政層級處理：自動拆分「市＋區/郡」結構，支援特殊行政結構

📖 詳細的南韓行政區處理邏輯請參閱南韓行政區處理文檔

🇹🇭 泰國地區優化

官方邊界資料：使用 COD-AB tha_admin3 sub-district / tambon 邊界資料
繁體中文翻譯：Admin1/Admin2 使用 Wikidata translator，缺少中文結果時回退 COD-AB 官方英文與官方泰文
最近距離最佳化：使用 Thailand Albers 投影計算幾何中心點，提升 Immich 最近點反向地理解析命中率
座標策略驗證：不使用 COD-AB 內建 center_lat / center_lon 作為預設，因其較接近官方代表點而非最近點模型下的最佳單點

📖 詳細的泰國行政區處理邏輯請參閱泰國行政區處理文檔

🇮🇩 印尼地區優化

官方村級圖資：使用 BIG（Badan Informasi Geospasial，印尼地理空間資訊局）官方 ArcGIS REST 服務發布的 desa（村級）邊界資料（版本 TASWIL20230928，含 38 省全量 83,461 筆可用 feature）
繁體中文翻譯：Admin1（省）與 Admin2（縣／市）使用 Wikidata translator 並以 P131 行政隸屬逐級驗證；缺少可靠中文標籤時回退 BIG 官方印尼文原文，Admin3（郡）/ Admin4（村）則保留印尼文原文
三時區解析：依 38 省 per-province 對照表解析印尼三時區（WIB Asia/Jakarta、WITA Asia/Makassar、WIT Asia/Jayapura）
最近距離最佳化：使用印尼 Albers 等積投影（+lat_1=1 +lat_2=-8 +lon_0=118）計算幾何中心點；multipart polygon 每個 part 各出一列，提升群島地形的最近鄰命中率（admin2 命中率 96.99%）

📖 詳細的印尼行政區處理邏輯請參閱印尼行政區處理文檔

🌏 其他地區優化

國教院官方譯名：整合國家教育研究院《外國地名譯名》（64,000+ 筆官方臺灣譯名），以名稱正規化匹配搭配座標驗證，為全球地名補洞並升級為官方譯名
信心分級保護：高信心（國碼一致＋距離合格＋無歧義）才覆寫既有譯名；具弱化訊號（地物標記、近距歧義等）僅補洞；無法消歧時保守放棄，杜絕同名錯配
GeoNames 後備：無官方譯名時使用 GeoNames 中文資料（經 OpenCC 轉換為臺灣正體），再無則回退英文

📖 詳細的全球翻譯處理邏輯請參閱全球翻譯處理文檔

更新地理資料

整合式部署

只需重新啟動 Immich 容器，即可自動更新地理資料。

手動部署

下載最新 release.zip，並解壓至指定位置。
重新提取照片元數據（與「使用方式-手動部署」相同）。

開發者：本地資料處理

1. 安裝依賴

本機 production 資料處理預設使用 Rust CLI。請先安裝 Rust toolchain，並確認系統可使用 unzip、pkg-config 與 PROJ development library（例如 Ubuntu 的 libproj-dev）。

官方預編譯 Binary

GitHub Releases 目前只提供 Linux x86_64 的預編譯 Rust CLI binary，主要供 GitHub Actions、Linux server 與 Immich container 類環境使用。macOS 與 Windows 目前請使用本地編譯方式。

本地編譯 Rust CLI

如需在非 Linux 環境或自訂 Linux 環境執行資料處理，請先安裝 Rust toolchain 與 PROJ development library，再執行：

cargo build --release

編譯完成後，binary 會位於：

target/release/immich-geodata

也可以直接用 cargo run 執行：

cargo run --release -- help

2. 提取原始地理資料

如果你需要處理新的國家或更新現有的地理資料來源，可以使用 extract 命令從 Shapefile 或 GeoJSON 提取資料。此步驟是選用的，僅在需要更新資料來源時執行。

臺灣資料提取

資料來源：國土測繪中心（NLSC）

# 1. 下載「村(里)界（TWD97經緯度）」資料並解壓縮
# 2. 執行提取命令
cargo run --release -- extract --country TW \
  --shapefile geoname_data/VILLAGE_NLSC_1140825/VILLAGE_NLSC_1140825.shp \
  --output meta_data/tw_geodata.csv

日本資料提取

資料來源：国土数値情報

# 1. 下載「行政区域データ（世界測地系）」並解壓縮
# 2. 執行提取命令
cargo run --release -- extract --country JP \
  --shapefile geoname_data/N03-20250101_GML/N03-20250101.shp \
  --output meta_data/jp_geodata.csv

南韓資料提取

資料來源：admdongkor

# 1. 從 admdongkor 專案下載官方行政區邊界資料並解壓縮
# 2. 執行提取命令
cargo run --release -- extract --country KR \
  --shapefile geoname_data/HangJeongDong_verYYYYMMDD.geojson \
  --output meta_data/kr_geodata.csv

泰國資料提取

資料來源：Thailand COD-AB

# 1. 下載 tha_admin_boundaries.shp.zip 並解壓縮
# 2. 使用 tha_admin3.shp 提取 Admin 3 / Tambon 邊界資料
cargo run --release -- extract --country TH \
  --shapefile geoname_data/tha_admin_boundaries/tha_admin3.shp \
  --output meta_data/th_geodata.csv

泰國提取會讀取或建立 geoname_data/TH_wikidata_cache.json，用於 Admin1/Admin2 繁中翻譯；Admin3 目前保留 COD-AB 官方英文。

提取完成後，執行 Rust release 時會自動整合這些資料。

印尼資料提取

資料來源：BIG（Badan Informasi Geospasial）官方 ArcGIS REST FeatureServer

# 1. 從 BIG 官方 REST 服務以分頁方式下載 desa 村級圖資（geometryPrecision=6，版本 TASWIL20230928）
#    下載方式與固定參數請參閱 docs/research/indonesia-handler.md
# 2. 執行提取命令
cargo run --release -- extract --country ID \
  --shapefile <path_to_BIG_desa_geojson> \
  --output meta_data/id_geodata.csv

印尼提取會讀取或建立 geoname_data/ID_wikidata_cache.json，用於 Admin1（省）/ Admin2（縣市）繁中翻譯；Admin3（郡）/ Admin4（村）保留 BIG 官方印尼文。詳細下載流程與固定參數請參閱印尼 handler 研究文件。

提取完成後，執行 Rust release 時會自動整合這些資料。

3. 完整資料處理流程

完成資料提取（或使用現有的資料）後，可以執行完整的資料處理流程來生成 release。

註冊 LocationIQ API

至 LocationIQ 註冊帳號，並取得 API Key。

執行資料處理

cargo run --release -- release \
  --locationiq-api-key "YOUR_API_KEY" \
  --country-code "US"

[!NOTE]

可以通過 cargo run -- help 查看更多選項。

--country-code 參數可指定需要處理的國家代碼，多個代碼之間使用空格分隔。

臺、日、韓、泰、印（TW/JP/KR/TH/ID）已改由官方圖資 handler 產生，無需也不應以 LocationIQ 處理；此流程僅用於為其他國家產生 metadata。

[!WARNING]

由於 LocationIQ 的 API 有請求次數限制 (可登入後於後台查看)，因此請注意要處理的國家的地名數量，以免超出限制。

本專案允許 LocationIQ 反向地理編碼查詢的進度恢復，若超過當日請求限制，可於更換 api 金鑰或次日繼續執行。

需加上 --pass-cleanup 參數，以取消重設資料夾功能： cargo run --release -- release --locationiq-api-key "YOUR_API_KEY" --country-code "US" --pass-cleanup。

4. Rust 驗證

Rust CLI 提供 dry-run contract，可在不呼叫外部 API 或下載網路的情況下驗證 release orchestration：

cargo run -- release \
  --dry-run \
  --locationiq-api-key "fixture" \
  --country-code "KR" "TH" \
  --batch-size 100 \
  --locationiq-qps 2

需要驗證 release archive 與 update_data.sh 所需目錄結構時，可使用 fixture mode 產生本地 smoke artifact：

cargo run -- release \
  --fixture-mode \
  --pass-locationiq \
  --output-folder /tmp/rust-release-smoke

目前 release 與 nightly production workflow 已切換為 Rust production path，並保留 Rust fixture release smoke 作為前置檢查。真實 GeoNames/Natural Earth 下載與 LocationIQ quota path 的自動測試仍需使用 fixture、stub 或明確 dry-run gate。

致謝

本專案基於 immich-geodata-cn 修改，特別感謝原作者 ZingLix 的貢獻。

授權條款

本專案採用 GPL 授權。

immich-geodata-zh-tw

About immich-geodata-zh-tw

Platforms

Languages

Links

README.md

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

設計理念

使用前後對比

目錄

支援地區與語言策略

資料來源

使用方式

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

手動部署

指定特定版本

行政區優化策略

🇹🇼 臺灣地區優化

🇯🇵 日本地區優化

🇰🇷 南韓地區優化

🇹🇭 泰國地區優化

🇮🇩 印尼地區優化

🌏 其他地區優化

更新地理資料

整合式部署

手動部署

開發者：本地資料處理

1. 安裝依賴

官方預編譯 Binary

本地編譯 Rust CLI

2. 提取原始地理資料

臺灣資料提取

日本資料提取

南韓資料提取

泰國資料提取

印尼資料提取

3. 完整資料處理流程

註冊 LocationIQ API

執行資料處理

4. Rust 驗證

致謝

授權條款