Skip to content

Commit 4e33c2a

Browse files
RxChi1dRxChi1d
committed
docs: add English README and update Chinese README
1 parent 087591a commit 4e33c2a

File tree

2 files changed

+224
-0
lines changed

2 files changed

+224
-0
lines changed

‎README.en.md

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# Immich Reverse Geocoding - Taiwan Localization
2+
3+
[繁體中文](README.md) | [English](README.en.md)
4+
5+
This project provides Taiwan-localized optimization for Immich's reverse geocoding functionality, aiming to improve geographical information accuracy and user experience. Main features include:
6+
7+
- **Chinese Localization**: Converting geographical names from home and abroad to Traditional Chinese conforming to Taiwan terminology.
8+
- **Administrative Division Optimization**: Solving the issue where Taiwan's municipalities and provincial cities/counties only display region names.
9+
- **Enhanced Taiwan Data Accuracy**: Utilizing official map data from **National Land Surveying and Mapping Center (NLSC)** of Taiwan to process geographical names and boundary data for Taiwan region, ensuring authoritative data sources.
10+
11+
> [!WARNING]
12+
> **Important Update Notice**
13+
>
14+
> This project has recently made the following important adjustments:
15+
> 1. **Deployment Script Changes**: The auto-update script for Docker `entrypoint` has been changed from `auto_update.sh` to `update_data.sh`, and now requires the `--install` parameter. Please make sure to update your `docker-compose.yml` configuration.
16+
> 2. **Version Tag Adjustments**:
17+
> - Auto-built versions now use the fixed `nightly` tag.
18+
> - Manually released stable versions will use semantic version tags (e.g., `v1.0.0`).
19+
>
20+
> Please carefully read the [Usage](#usage) and [Specify Specific Version](#specify-specific-version) sections for the latest configuration instructions.
21+
22+
### Before and After Comparison
23+
![Before and After Comparison](./image/example.png)
24+
25+
## Table of Contents
26+
27+
- [Immich Reverse Geocoding - Taiwan Localization](#immich-reverse-geocoding---taiwan-localization)
28+
- [Before and After Comparison](#before-and-after-comparison)
29+
- [Table of Contents](#table-of-contents)
30+
- [Data Sources](#data-sources)
31+
- [Usage](#usage)
32+
- [Integrated Deployment (Recommended, convenient for future updates)](#integrated-deployment-recommended-convenient-for-future-updates)
33+
- [Manual Deployment](#manual-deployment)
34+
- [Specify Specific Version](#specify-specific-version)
35+
- [Taiwan Localization Logic](#taiwan-localization-logic)
36+
- [Update Geographic Data](#update-geographic-data)
37+
- [Integrated Deployment](#integrated-deployment)
38+
- [Manual Deployment](#manual-deployment-1)
39+
- [Local Data Processing](#local-data-processing)
40+
- [Acknowledgments](#acknowledgments)
41+
- [License](#license)
42+
43+
## Data Sources
44+
45+
The geographic data used in this project mainly comes from the following sources:
46+
47+
1. **GeoNames** ([geonames.org](https://www.geonames.org/)): As the global geographic location database foundation.
48+
2. **National Land Surveying and Mapping Center (NLSC)** of Taiwan:
49+
- Source: [NLSC Open Data Platform](https://whgis-nlsc.moi.gov.tw/Opendata/Files.aspx)
50+
- Dataset: Village Boundaries (TWD97 Latitude/Longitude), Version 1131128 (or newer)
51+
- Purpose: As the primary data source for Taiwan region village boundaries and administrative district names, ensuring data accuracy and authority.
52+
3. **LocationIQ**: Used for processing reverse geocoding requests for non-Taiwan regions, calibrating administrative division levels.
53+
4. **Ministry of Economic Affairs International Trade Administration & Ministry of Foreign Affairs of Taiwan**: As reference sources for Chinese translations of some countries/regions.
54+
55+
> **NOTE**:
56+
> Since Immich's reverse geocoding functionality is based on its loaded database (this project mainly relies on GeoNames and NLSC data) and uses nearest distance principle to match place names, some results may not be completely precise or may differ from expectations.
57+
58+
## Usage
59+
60+
This project supports the following two deployment methods:
61+
62+
1. Integrated deployment (suitable for Immich's docker-compose deployment, ensures automatic loading of latest Taiwan localization data when container starts).
63+
64+
2. Manual deployment (suitable for custom deployment environments, allows manual download and configuration of localization data).
65+
66+
### Integrated Deployment (Recommended, convenient for future updates)
67+
68+
1. **Modify `docker-compose.yml` configuration**
69+
Add `entrypoint` setting to the `immich_server` service to automatically download the latest geographic data when the container starts:
70+
```yaml
71+
services:
72+
immich_server:
73+
container_name: immich_server
74+
75+
# Other configurations omitted
76+
77+
entrypoint: [ "tini", "--", "/bin/bash", "-c", "bash <(curl -sSL https://raw.githubusercontent.com/RxChi1d/immich-geodata-zh-tw/refs/heads/main/update_data.sh) --install && exec /bin/bash start.sh" ]
78+
```
79+
> **NOTE**:
80+
> - The `entrypoint` will first execute this project's `update_data.sh` script when the container starts, automatically downloading and configuring Taiwan localization data, then execute Immich server's `start.sh` to start the service.
81+
> - Integrated deployment also supports specifying specific version downloads. For details, please refer to the [Specify Specific Version](#specify-specific-version) section.
82+
83+
2. **Restart Immich**
84+
Execute the following command to restart Immich：
85+
```bash
86+
# If using docker-compose deployment
87+
docker compose down && docker compose up
88+
```
89+
- After startup, check if logs show messages like `10000 geodata records imported` to confirm geodata has been successfully updated.
90+
- If not updated, please modify `geodata/geodata-date.txt` to a newer timestamp, ensuring it's later than Immich's last load time.
91+
92+
3. **Re-extract photo metadata**
93+
Log into Immich admin backend, go to **Administration > Tasks**, click **Extract Metadata > All** to trigger re-extraction of photo metadata. After completion, all photos' geographic information will be displayed in Chinese.
94+
Newly uploaded photos require no additional operations and can directly support Chinese search.
95+
96+
### Manual Deployment
97+
98+
1. **Modify `docker-compose.yml` configuration**
99+
Add the following mappings to `volumes` (please adjust paths according to actual environment):
100+
```yaml
101+
volumes:
102+
- /mnt/user/appdata/immich/geodata:/build/geodata:ro
103+
- /mnt/user/appdata/immich/i18n-iso-countries/langs:/usr/src/app/node_modules/i18n-iso-countries/langs:ro
104+
```
105+
106+
2. **Download Taiwan localization data**
107+
Two download methods are provided:
108+
109+
(1) **Automatic download**
110+
Refer to the `update_data.sh` script in this project, modify `DOWNLOAD_DIR` to the folder path storing geodata and i18n-iso-countries, and execute the script:
111+
```bash
112+
bash update_data.sh
113+
```
114+
> **NOTE**:
115+
> - Manual deployment also supports specifying specific version downloads. For details, please refer to the [Specify Specific Version](#specify-specific-version) section.
116+
> - UnRAID users can execute the script through the User Scripts plugin.
117+
118+
(2) **Manual download**
119+
Go to the [Release page](https://github.com/RxChi1d/immich-geodata-zh-tw/releases) to find the required version, download the corresponding `release.tar.gz` or `release.zip`, and extract it to the specified location.
120+
121+
3. **Restart Immich and re-extract photo metadata**
122+
Same as steps 2 and 3 in [**Integrated Deployment**](#integrated-deployment).
123+
124+
## Specify Specific Version
125+
126+
In some cases (e.g., when the latest release has issues), you may need to download or rollback to a specific release version. This project's update script supports specifying the release tag to download through the `--tag` parameter.
127+
128+
**How to find available Tags?**
129+
Please go to this project's [Releases page](https://github.com/RxChi1d/immich-geodata-zh-tw/releases) to view all available release tag names (e.g., `v1.0.0`, `nightly`, etc.).
130+
131+
**Usage Examples:**
132+
133+
1. **Integrated Deployment (`entrypoint` in `docker-compose.yml`)**
134+
Add `--tag <tag_name>` after the entrypoint command:
135+
```yaml
136+
entrypoint: [ "tini", "--", "/bin/bash", "-c", "bash <(curl -sSL https://raw.githubusercontent.com/RxChi1d/immich-geodata-zh-tw/refs/heads/main/update_data.sh) --install --tag <tag_name> && exec /bin/bash start.sh" ]
137+
```
138+
Replace `<tag_name>` with the specific tag name you want to download. If `--tag` is omitted, the latest release (`latest`) is downloaded by default.
139+
140+
2. **Manual Deployment (`update_data.sh`)**
141+
Add `--tag <tag_name>` when executing the script:
142+
```bash
143+
bash update_data.sh --tag <tag_name>
144+
```
145+
Replace `<tag_name>` with the specific tag name you want to download. If `--tag` is omitted, the latest release (`latest`) is downloaded by default.
146+
147+
> **NOTE**: The script will first verify whether the specified tag exists in GitHub Releases. If the tag is invalid, it will prompt an error and terminate execution, so please ensure the tag is valid before execution.
148+
149+
## Taiwan Localization Logic
150+
151+
This project adopts more precise and locally-tailored localization logic for Taiwan region geographic information processing:
152+
153+
1. **NLSC data as the core**:
154+
* Taiwan's administrative boundaries and names are mainly based on **village boundary map data published by the National Land Surveying and Mapping Center (NLSC)**. This ensures **accuracy** of geographic information.
155+
* By processing NLSC village data, we can reverse-resolve geographic coordinates accurately to the village level, thus providing more precise township and county/city levels.
156+
157+
2. **Administrative division level definitions**:
158+
* **Level 1 Administrative Division (Admin1)**: Corresponds to Taiwan's **22 municipalities and provincial cities/counties** (e.g., Taipei City, Keelung City, Changhua County).
159+
* **Level 2 Administrative Division (Admin2)**: Corresponds to **townships, towns, cities, districts** under each county/city (e.g., Banqiao District in New Taipei City, Changhua City in Changhua County).
160+
* **Level 3 Administrative Division (Admin3)**: Corresponds to **villages and wards** in NLSC data.
161+
* **Level 4 Administrative Division (Admin4)**: Currently not used.
162+
163+
3. **Chinese name processing**:
164+
* Geographic names within Taiwan (counties/cities, townships/towns/cities/districts, villages/wards) **directly adopt official names provided by NLSC map data**.
165+
* Geographic names outside Taiwan mainly refer to the **GeoNames** database, where country name translations adopt official translations provided by **Ministry of Economic Affairs International Trade Administration** and **Ministry of Foreign Affairs of Taiwan**, ensuring Traditional Chinese names that conform to Taiwan terminology habits.
166+
167+
Through the above logic, this project aims to provide reverse geocoding results that are more aligned with Taiwan's actual situation and more accurate.
168+
169+
## Update Geographic Data
170+
171+
### Integrated Deployment
172+
173+
Simply restart the Immich container to automatically update geographic data.
174+
175+
### Manual Deployment
176+
177+
1. Download the latest release.zip and extract it to the specified location.
178+
179+
2. Re-extract photo metadata (same as [Manual Deployment](#manual-deployment)).
180+
181+
## Local Data Processing
182+
183+
1. **Install Dependencies**
184+
Execute the following command to install required Python dependencies：
185+
186+
```bash
187+
pip install -r requirements.txt
188+
```
189+
190+
Or manually install the following packages：
191+
192+
| Package | Version |
193+
| -------- | --------- |
194+
| loguru | 0.7.3 |
195+
| opencc | 1.1.9 |
196+
| polars | 1.27.1 |
197+
| regex | 2024.11.6 |
198+
| requests | 2.32.3 |
199+
| tqdm | 4.67.1 |
200+
201+
2. Register an account at [LocationIQ](https://locationiq.com/) and obtain an API Key.
202+
203+
3. **Execute `main.py`**
204+
```bash
205+
python main.py release --locationiq-api-key "YOUR_API_KEY" --country-code "TW" "JP"
206+
```
207+
> **NOTE:**
208+
> - You can view more options through `python main.py --help` or `python main.py release --help`.
209+
> - The `--country-code` parameter can specify country codes to process, multiple codes separated by spaces. (Currently only tested with TW, JP, KR)
210+
211+
> **WARNING:**
212+
> - Since LocationIQ API has request limits (can be checked in the backend after login), please pay attention to the number of place names in the countries to be processed to avoid exceeding limits.
213+
> - This project allows LocationIQ reverse geocoding query progress recovery. If daily request limits are exceeded, you can continue execution after changing API keys or the next day.
214+
> - Need to add `--pass-cleanup` parameter to cancel folder reset function: `python main.py release --locationiq-api-key "YOUR_API_KEY" --country-code "TW" "JP" --pass-cleanup`.
215+
216+
## Acknowledgments
217+
218+
This project is modified based on [immich-geodata-cn](https://github.com/ZingLix/immich-geodata-cn), special thanks to the original author [ZingLix](https://github.com/ZingLix) for their contribution.
219+
220+
## License
221+
222+
This project is licensed under GPL.

‎README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
# Immich 反向地理編碼 - 臺灣特化
2+
3+
[繁體中文](README.md) | [English](README.en.md)
24

35
本專案為 Immich 提供反向地理編碼功能的臺灣特化優化，旨在提升地理資訊的準確性及使用體驗。主要功能包括：
46

0 commit comments

Comments
 (0)