About Immich Geodata Zh Tw

Immich 反向地理編碼 - 臺灣特化，提供更精確的地理資訊與中文化優化，改善行政區顯示與翻譯準確度。

Alternatives to Immich Geodata Zh Tw

View All

Traccar Geocoder

Traccar reverse geocoding service

233

Published by

rxchi1d

Visit View Profile

Immich Geodata Zh Tw

View on GitHub

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

Need Help Installing Immich Geodata Zh Tw?

Alternatives to Immich Geodata Zh Tw

Traccar Geocoder

Immich Geodata Zh Tw

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

設計理念

使用前後對比

目錄

支援地區與語言策略

資料來源

使用方式

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

手動部署

指定特定版本

行政區優化策略

🇹🇼 臺灣地區優化

🇯🇵 日本地區優化

🇰🇷 南韓地區優化

🇹🇭 泰國地區優化

🇮🇩 印尼地區優化

🌏 其他地區優化

更新地理資料

整合式部署

手動部署

開發者：本地資料處理

1. 安裝依賴

官方預編譯 Binary

本地編譯 Rust CLI

2. 提取原始地理資料

臺灣資料提取

日本資料提取

南韓資料提取

泰國資料提取

印尼資料提取

3. 完整資料處理流程

註冊 LocationIQ API

執行資料處理

4. Rust 驗證

致謝

授權條款