Immich 地理編碼臺灣特化 - immich-geodata-zh-tw 專案介紹與使用教學

本文介紹 immich-geodata-zh-tw 專案，這是一個專為繁體中文使用者打造的 Immich 反向地理編碼優化方案。除了針對臺灣進行深度的在地化處理（繁體中文、補齊鄉鎮市區層級），也涵蓋日本、南韓、東南亞等熱門旅遊地區的在地化圖資與譯名優化，全球其餘地區則補上臺灣慣用的中文譯名，並提供穩定的自動化更新機制。

在「Immich 部署、設定與反向代理 - Google 相簿的最佳開源替代方案」中，我們完成了 Immich 的基本部署。但你可能會發現幾個問題：

• 照片的地理資訊都是 英文，例如 Immich 的原始輸出會顯示 “Sanzhi, Taipei, Taiwan, Province of China”。
• 行政區顯示不完整，無法定位到鄉鎮市區，甚至顯示錯誤的地點。
• 非英語系地名顯示不友善：出國旅遊拍的照片往往只顯示羅馬拼音或不精準的英文標籤，缺乏讀者習慣的漢字或中文譯名。

為了解決這些問題，我開發了 immich-geodata-zh-tw 專案，透過優化 Immich 的反向地理編碼資料庫，提供符合臺灣使用者習慣的地理資訊體驗。

RxChi1d/immich-geodata-zh-tw

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

Rust

93

6

為什麼 Immich 的相片地點會顯示英文？

#

Immich 原生的反向地理編碼主要依賴 GeoNames 全球資料庫，這對繁體中文使用者造成了幾個主要問題：

1. 英文地名：缺乏繁體中文翻譯。
2. 行政區顯示不完整：只有縣市名稱，看不到更細緻的鄉鎮市區層級。
3. 地名解析不夠精準：缺乏在地化的邊界資料，導致有時候會顯示錯誤的地點。

例如，在臺北 101 拍攝的照片可能只顯示 “Taipei, Taiwan, Province of China”，而非「臺灣 臺北市 信義區」。同樣地，日本的「東京都千代田区」也會變成羅馬拼音的 “Chiyoda, Tokyo, Japan”。

本專案透過引入各國官方或開源的高精確度圖資，並結合自動化翻譯引擎，解決上述問題。

想知道為什麼替換幾個純文字檔就能改變 Immich 顯示的地名，可以參考系列技術篇的反向地理編碼是怎麼運作的。

immich-geodata-zh-tw 支援哪些地區

#

專案以各國官方測繪機構圖資為核心深度處理，並搭配逆地理查詢與全球地名庫，提供不同層度的在地化支援：

使用前後對比

#

不僅地名更精確，中文搜尋體驗也大幅提升！此外，專案具備「地名點剪枝」機制，在保證查詢結果完全一致的前提下，刪除了全球 33.5% 的冗餘點位，縮減儲存空間並讓密集地區的查詢速度提升達 3 倍。

安裝步驟

#

開始之前

#

請先確認以下條件：

• Immich 已經部署完成且可正常啟動（尚未部署請先參考「Immich 部署、設定與反向代理」）
• 你有權限修改 docker-compose.yml 並重啟容器
• 整合式部署需要容器啟動時能連到 github.com；環境無法對外連線請改用手動部署
• 知道自己的 Immich 版本（本專案支援 v2 與 v3。只有停留在 v1 舊版的環境才需要留意文中標註的路徑差異）
• 照片本身含有 GPS 資訊，否則 Immich 無從判斷地點

多數人適用方法 A：用 Docker Compose 部署、容器啟動時連得到 GitHub，在 docker-compose.yml 加一行就結束，之後也會自動保持更新。如果有特殊的掛載需求，或環境本來就連不到外網，就走方法 B 自己下載資料。Immich 沒有跑在容器裡的話（例如 macOS 原生安裝、LXC 或裸機），直接看「其他部署方式」那一節。

方法 A：整合式部署 🚀（推薦）

#

若使用 Docker Compose 部署 Immich，這是最簡單且能自動保持更新的方法。

如果是使用 Synology Docker 套件，請參考 Chiyuan Chien 的 Immich 相簿地理位置如何改以中文顯示？。

1. 修改 docker-compose.yml

#

在 immich_server 服務中加入 entrypoint 設定：

services:
  immich_server:
    container_name: immich_server
    # ...其餘設定省略
    # 注意：這裡使用 releases/latest/download 確保下載到穩定的釋出版本
    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" ]

以 Immich 官方的 docker-compose.yml 範例 為例，完整內容如下圖：

2. 重啟 Immich

#

docker compose down && docker compose up -d

3. 確認安裝成功

#

查看容器日誌：

docker logs immich_server

檢查重點：

1. 是否有看到 immich-geodata-zh-tw 的執行與下載訊息。
   若看到類似以下訊息，表示腳本執行成功：
   

   

   腳本最後若輸出 驗證通過，代表資料確實寫入 Immich 會讀取的位置（含決定國家名稱顯示的 en.json），這是比日誌關鍵字更可靠的判斷依據。
2. Immich 啟動後是否顯示 10000 geodata records imported（表示成功載入資料）。
   

   

到這裡整合式部署就完成了。如果你的 Immich 裡已經有照片，還需要執行最後一步：「重新擷取照片詮釋資料」，舊照片才會套用新的地理資訊。

方法 B：手動部署 🛠️

#

適用於有特殊掛載需求或無法連外網的環境。

1. 修改 docker-compose.yml volumes

#

volumes:
  - /path/to/your/immich/geodata:/build/geodata:ro
  - /path/to/your/immich/i18n-iso-countries/langs:/usr/src/app/server/node_modules/i18n-iso-countries/langs:ro

2. 下載資料

#

先取得下載腳本：

curl -sSL https://github.com/RxChi1d/immich-geodata-zh-tw/releases/latest/download/update_data.sh -o update_data.sh

接著編輯腳本開頭的 DOWNLOAD_DIR 變數（在檔案前段的設定區，搜尋 DOWNLOAD_DIR= 即可找到），填入上方兩個掛載路徑的共同上層目錄（以上面的範例來說就是 /path/to/your/immich），然後執行：

bash update_data.sh

完成後會得到這樣的結構，不需要再手動搬移檔案：

/path/to/your/immich/geodata/
/path/to/your/immich/i18n-iso-countries/langs/

也可以直接到 GitHub Releases 頁面下載 release.tar.gz 或 release.zip，解壓縮後把 geodata 與 i18n-iso-countries 兩個資料夾放到相同位置。

3. 重啟服務

#

docker compose down && docker compose up -d

完成後，參考「3. 確認安裝成功」驗證是否導入成功。

其他部署方式（macOS 原生 worker、LXC 與裸機） 🖥️

#

Immich 沒有跑在 Docker 容器裡時也能安裝，例如 immich-apple-silicon 或 LXC，只是指令要在執行 microservices worker 的那台機器上操作，因為地理資料只會在該服務啟動時匯入。

安裝前建議先讓腳本印出它打算安裝的位置：

bash <(curl -sSL https://github.com/RxChi1d/immich-geodata-zh-tw/releases/latest/download/update_data.sh) --print-paths

確認無誤後把 --print-paths 換成 --install 即可安裝；路徑不正確時可用 IMMICH_SERVER_ROOT 與 IMMICH_BUILD_DATA 指定。macOS 加速器的重啟方式、LXC 與裸機的 sudo 注意事項等細節，請參考專案的 README「非容器部署」 與 macOS 加速器設定指南。

最後一步（所有部署方式共通）：重新擷取照片詮釋資料 📸

#

資料導入後，必須重新擷取詮釋資料，舊照片才會套用新的地理資訊（新上傳照片會自動套用）。

1. 登入 Immich 後台

   

2. 進入 系統管理 (Administration) → 任務 (Jobs)

   

3. 找到 擷取詮釋資料 (Extract Metadata)，點擊 全部 (All)

   

這時，舊照片的地理資訊就會被更新成中文地名，而新上傳的照片則會直接套用！

進階功能

#

指定特定版本

#

若最新的 Release 有問題，或想固定使用特定版本（例如 v3.3.0），可以使用 --tag 參數。腳本本身一律從最新版本取得，只有資料版本由 --tag 決定。

整合式部署： 修改 entrypoint 中的指令：

entrypoint: [ "tini", "--", "/bin/bash", "-c", "bash <(curl -sSL https://github.com/RxChi1d/immich-geodata-zh-tw/releases/latest/download/update_data.sh) --install --tag v3.3.0 && exec start.sh" ]

手動部署：

bash update_data.sh --install --tag v3.3.0

可用版本請查看 Releases 頁面。若環境無法連外網，也可以先下載 release.tar.gz，再用 --archive 安裝，詳細參數說明見專案的 update_data.sh 使用說明。

常見問題 🔧

#

Q: 如何更新資料？
A: 整合式部署直接重啟 docker compose 即可自動更新；手動部署重新執行一次 bash update_data.sh 後重啟容器；其他部署方式則重新執行同一條 --install 指令後重啟 Immich 服務。更新後別忘了視情況重新擷取詮釋資料。

Q: 導入訊息看不到，中文沒套用？
A: 檢查日誌是否有 geodata records imported；若沒有，請參考「沒看到導入訊息？」確認匯入條件。別忘了重新擷取詮釋資料。

Q: 縣市名稱已經更新為繁體中文了，但國家名稱卻還是英文？
A: 可能原因為您使用的 Immich 版本為 1.136.0 以後的新版本，但使用的 immich-geodata-zh-tw 版本小於 v1.2.0。只要使用最新發布（預設）或 v1.2.0 以上版本即可解決此問題。

相關連結：Issue #8

Q: 容器一直重啟，報 main.js not found？
A: 這通常發生在 Immich v1.142.0+ 版本。因為 Immich 更改了啟動檔名，如果您使用了舊版的 entrypoint 指令（包含 exec node dist/main 或 exec /bin/bash start.sh 之類的），請根據「方法 A：整合式部署 🚀（推薦）」，更新 docker-compose.yml 中的 entrypoint 配置。

相關連結：Issue #13

Q: 有些照片的地點跟實際位置有落差？
A: Immich 依照最近距離原則比對地名，靠近行政區邊界的座標可能被歸到鄰近的行政區，小型島嶼或特殊地形也可能無法精確對應。這是 Immich 的解析方式所致，並非資料錯誤。這套最近鄰查詢的運作方式詳見反向地理編碼是怎麼運作的。

Q: 如何移除或還原成原本的地名？
A: 整合式部署刪掉 docker-compose.yml 裡的 entrypoint 那一行；手動部署則移除兩條 volume 掛載。重啟容器後 Immich 會改用官方預設的 GeoNames 資料（若沒有立即生效，同樣是 geodata/geodata-date.txt 的比對問題），最後再重新擷取一次詮釋資料即可。

總結

#

immich-geodata-zh-tw 透過整合官方測繪圖資、逆地理查詢與在地化譯名庫，讓相簿中的旅遊地點整理更貼近臺灣使用者的閱讀習慣。

如果你想知道這些地理資料是怎麼做出來的，包括 Immich 到底讀哪幾個檔案、各國圖資怎麼處理、地名怎麼翻譯與驗證，系列技術篇拆解了完整流程，可以從反向地理編碼是怎麼運作的開始。

如果您覺得這個專案有幫助，歡迎到 GitHub 給我一顆星星 ⭐ 支持！

參考資源

#

• 專案 GitHub 倉庫
• GeoNames (全球基礎資料)
• 國土測繪中心開放資料 (臺灣)
• 国土数値情報ダウンロード (日本)
• admdongkor (南韓)
• COD-AB Thailand (泰國)
• 印尼地理空間資訊局 BIG (印尼)
• 國家教育研究院《外國地名譯名》
• OpenStreetMap (全球輔助資料)