docs: 英文 README 设为默认并添加 AGPL 许可

2026-09-26 16:41:54 +08:00 · 2026-09-24 15:31:47 +08:00
parent f4712f7fb2
commit 228b67b210
6 changed files with 1406 additions and 724 deletions
@@ -4,149 +4,155 @@

 ### iOS Location Service Research & Testing Framework

-一个用于 **iOS 定位服务研究、软件开发测试和 QA 验证** 的开源项目。
+An open-source project for **iOS location-service research, software development testing, and QA validation**.

-项目通过本机代理或第三方代理客户端，对 Apple 定位服务的指定响应进行测试环境模拟，帮助开发者验证应用在
-不同地理位置和定位场景下的行为。
+The project uses either an on-device proxy or a third-party proxy client to simulate selected Apple location-service
+responses in a controlled test environment.

-> ⚠️ **iOS 27 beta 6 起，系统已禁止对 `gs-loc.apple.com` 进行 MITM 拦截。** 目前该版本及之后的 beta 版本暂时无法使用本项目，等待后续适配方案。
+> ⚠️ **Starting with iOS 27 beta 6, the system blocks MITM interception of `gs-loc.apple.com`.** This project is
+> temporarily unusable on that version and later betas until a workaround is found.

 [![iOS 15+](https://img.shields.io/badge/iOS-15%2B-111111?logo=apple)](project.yml)
 [![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138)](project.yml)
 [![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go)](Core/go.mod)
 [![Version](https://img.shields.io/badge/version-v1.0.7-2563EB)](docs/CHANGELOG.md)

-[功能概览](#功能概览) ·
-[工作原理](#工作原理) ·
-[快速开始](#快速开始) ·
-[构建项目](#构建项目) ·
-[English](README.en.md)
+[Features](#feature-overview) ·
+[How It Works](#how-it-works) ·
+[Quick Start](#quick-start) ·
+[Build](#building-the-project) ·
+[中文](README.zh-CN.md)

 </div>

 > [!IMPORTANT]
-> 本项目用于学习研究、自有设备测试、软件开发和 QA 验证。
+> Use this project only for education, research, testing on devices you own, software development, and QA validation.
 >
-> 请仅在你拥有或获得授权的设备、网络和软件环境中使用，并遵守当地法律法规、网络管理规定以及相关服务条
-> 款。
+> Use it only on devices, networks, and software environments that you own or are authorized to test. Follow applicable
+> laws, network policies, and service terms.
 >
-> 本项目不保证兼容所有 iOS 版本或第三方应用，也不承诺绕过第三方应用的安全策略、业务限制或服务规则。
+> The project does not guarantee compatibility with every iOS version or third-party app, and it does not promise to
+> bypass third-party security controls, business restrictions, or service rules.

-## 项目定位
+## Project Scope

-Location Spoofer 是一个面向 iOS 定位服务行为研究和开发测试的工具。
+Location Spoofer is a tool for studying iOS location-service behavior and testing location-dependent software.

-它提供：
+It provides:

- 原生地图选点和位置场景切换；
- Apple 定位服务响应的测试环境模拟；
- 本地代理和第三方代理两种运行模式；
- 坐标标准识别与 WGS-84 / GCJ-02 双坐标管理；
- 环境检测、运行日志和问题诊断；
- 收藏位置和上次地图状态恢复。
+- Native map selection and location-scenario switching;
+- Controlled simulation of selected Apple location-service responses;
+- App Mode and Third-party Proxy Mode;
+- Map coordinate detection with paired WGS-84 and GCJ-02 values;
+- Environment checks, runtime logs, and diagnostics;
+- Favorite locations and restoration of the previous map state.

-项目不修改目标 App 的源代码，也不提供远程控制或数据采集服务。
+The project does not modify the target app's source code and does not provide telemetry, remote control, or data
+collection services.

-## 功能概览
+## Feature Overview

- **原生地图交互**
-    - 使用 MapKit 显示地图和系统蓝点；
-    - 支持搜索、点击选点、拖动地图中心和缩放；
-    - 支持收藏位置和恢复上次选点；
-    - 当前选点同时显示国内坐标和国际坐标，可分别复制。
+- **Native map interaction**
+  - Uses MapKit for the map and system blue dot;
+  - Supports search, map taps, center-point dragging, and zooming;
+  - Supports favorites and restoration of the latest selection;
+  - Shows both domestic and international coordinate representations with separate copy actions.

- **定位服务响应模拟**
-    - 通过代理层处理指定的 Apple 定位服务请求；
-    - 在测试环境中返回选定的坐标数据；
-    - 不需要修改目标 App 代码。
+- **Location-service response simulation**
+  - Processes only the Apple location-service requests defined by the project;
+  - Returns the selected coordinates in a controlled test environment;
+  - Does not require changes to the target app.

- **双运行模式**
-    - APP 模式：在设备内运行 Go 代理，仅支持当前 Wi-Fi 网络；
-    - 第三方代理模式：通过支持的代理客户端覆盖 Wi-Fi、4G 或 5G，具体能力取决于客户端。
+- **Two runtime modes**
+  - App Mode: runs the Go proxy on-device and covers only the current Wi-Fi network;
+  - Third-party Proxy Mode: uses a supported proxy client and may cover Wi-Fi, 4G, or 5G depending on that client.

- **环境检测**
-    - APP 模式检测本地代理、证书信任和请求链路；
-    - 第三方代理模式检测 WLOC 配置接口和模块响应；
-    - 失败时提供对应的配置或诊断入口。
+- **Environment checks**
+  - App Mode checks the local proxy, CA trust, and request path;
+  - Third-party Proxy Mode checks the WLOC configuration API and module response;
+  - Failures route to the relevant setup or diagnostics screen.

- **开发调试**
-    - 运行日志；
-    - 日志复制和清理；
-    - 坐标标准变化记录；
-    - 脱敏问题报告生成。
+- **Development diagnostics**
+  - Runtime logs;
+  - Log copy and cleanup;
+  - Map coordinate-system change records;
+  - Sanitized issue-report generation.

-## 工作原理
+## How It Works

-### APP 模式
+### App Mode

-APP 模式在设备内运行本地 Go 代理，并通过当前 Wi-Fi 的手动 HTTP 代理让指定请求经过本地代理。
+App Mode runs the local Go proxy inside the app. A manual HTTP proxy on the current Wi-Fi routes the selected requests
+through that on-device proxy.

 ```text
-iOS 定位请求
+iOS location request
      │
-      │ 当前 Wi-Fi 手动 HTTP 代理
+      │ Manual HTTP proxy on the current Wi-Fi
      ▼
-设备内 wloccore Go 代理
+On-device wloccore Go proxy
      │
-      │ 处理指定 Apple 定位服务请求
+      │ Handle selected Apple location-service requests
      ▼
-Apple 定位服务响应
+Apple location-service response
      │
-      │ 测试坐标响应
+      │ Test coordinate response
      ▼
-系统和应用读取定位结果
+The system and apps read the location result
 ```

-APP 模式：
+App Mode:

- 不创建 Network Extension；
- 不显示或占用系统 VPN；
- 只覆盖当前 Wi-Fi 网络；
- 需要配置当前 Wi-Fi 的手动 HTTP 代理；
- 需要安装并信任 App 生成的本机 CA；
- 代理只处理项目定义的 Apple 定位服务和环境验证请求，不是通用网络抓包工具。
+- Does not create a Network Extension;
+- Does not display or occupy the system VPN slot;
+- Covers only the current Wi-Fi network;
+- Requires a manual HTTP proxy on that Wi-Fi network;
+- Requires installation and trust of the CA generated by the app;
+- Handles only the Apple location-service and environment-verification traffic defined by the project. It is not a
+  general-purpose packet capture tool.

-### 第三方代理模式
+### Third-party Proxy Mode

-第三方代理模式不启动 App 内置 Go 代理，也不使用 App 生成的 CA。
+Third-party Proxy Mode does not start the app's Go proxy and does not use the CA generated by the app.

 ```text
-地图选点
+Map selection
  │
-  │ WGS-84 坐标
+  │ WGS-84 coordinates
  ▼
-WLOC 配置接口
+WLOC configuration API
  │
  ▼
-第三方代理客户端保存配置
+Third-party proxy client stores the configuration
  │
  ▼
-第三方代理客户端处理定位服务请求
+Third-party client processes location-service requests
 ```

-在该模式下：
+In this mode:

- App 负责地图选点、收藏、坐标同步和清除；
- 第三方客户端负责代理/VPN、MITM、证书和规则执行；
- 坐标持久化由第三方客户端负责；
- 是否支持 Wi-Fi、4G 或 5G 取决于客户端；
- App 关闭后，第三方客户端中的配置可能继续生效。
+- The app owns map selection, favorites, coordinate synchronization, and coordinate clearing;
+- The third-party client owns proxy/VPN, MITM, certificates, and rule execution;
+- The third-party client owns coordinate persistence;
+- Wi-Fi, 4G, and 5G support depends on the client;
+- The configuration may remain active after Location Spoofer closes.

-#### 配置接口与客户端适配
+#### Configuration API and Client Integration

-App 不会把坐标上传到项目服务器。它会发起以下 GET 请求，第三方客户端必须在设备本地拦截：
+The app does not upload coordinates to a project server. It sends the following GET request, which the third-party
+client must intercept locally on the device:

 ```text
 https://gs-loc.apple.com/wloc-settings/save
 ```

-| 操作 | 查询参数 | 用途 |
+| Action | Query parameters | Purpose |
 |---|---|---|
-| 查询 | `action=query` | 检查模块是否连接，并读取当前保存的坐标 |
-| 保存 | `lon=<WGS-84 经度>&lat=<WGS-84 纬度>&acc=<精度>` | 保存当前选点 |
-| 清除 | `action=clear` | 删除已保存的测试坐标 |
+| Query | `action=query` | Verify module connectivity and read the stored coordinate |
+| Save | `lon=<WGS-84 longitude>&lat=<WGS-84 latitude>&acc=<accuracy>` | Store the selected coordinate |
+| Clear | `action=clear` | Remove the stored test coordinate |

-拦截脚本必须返回 HTTP 200 和 JSON：
+The interception script must return HTTP 200 with JSON:

 ```json
 {
@@ -157,170 +163,178 @@ https://gs-loc.apple.com/wloc-settings/save
 }
 ```

-失败时返回：
+Failures use:

 ```json
 {
  "success": false,
-  "error": "错误说明"
+  "error": "Error description"
 }
 ```

-查询时没有已保存坐标，可以返回 `{"success":false,"error":"无已保存的坐标"}`。App 会把它识别为
-“模块已连接，但虚拟定位未开启”。保存成功时，响应中的经纬度必须与请求中的 WGS-84 坐标一致。
+When no coordinate is stored, a query may return `{"success":false,"error":"无已保存的坐标"}`. The app interprets
+that response as “module connected, virtual location inactive.” A successful save response must echo the requested
+WGS-84 longitude and latitude.

-要适配新的第三方客户端，需要：
+To integrate another third-party client:

-1. 为 `gs-loc.apple.com/wloc-settings/save` 添加 HTTP 请求脚本，解析上述参数并返回约定 JSON；
-2. 使用客户端的持久化存储保存坐标、精度和可选状态；
-3. 为 `gs-loc.apple.com` 和 `gs-loc-cn.apple.com` 配置 HTTPS 解密；
-4. 拦截 `gs-loc(-cn).apple.com/clls/wloc` 响应，读取同一份持久化数据并修改 WLOC 响应；
-5. 提供可订阅的模块文件，并确认查询、保存、清除和定位恢复都能在真机完成。
+1. Add an HTTP request script for `gs-loc.apple.com/wloc-settings/save` that parses the parameters and returns the
+   specified JSON;
+2. Store coordinates, accuracy, and optional state in the client's persistent storage;
+3. Enable HTTPS decryption for `gs-loc.apple.com` and `gs-loc-cn.apple.com`;
+4. Intercept `gs-loc(-cn).apple.com/clls/wloc` responses, read the same persistent data, and modify the WLOC response;
+5. Publish an importable module and verify query, save, clear, and location restoration on a real device.

-App 只验证配置接口的 HTTP 状态、JSON 格式和坐标回读，不管理第三方客户端的证书、MITM、VPN 或代理状态。
+The app validates only the configuration endpoint's HTTP status, JSON shape, and coordinate round trip. It does not
+manage the third-party client's certificate, MITM, VPN, or proxy state.

-不要同时启用 APP 模式代理和第三方代理模式，避免两个代理链路互相干扰。
+Do not enable App Mode interception and Third-party Proxy Mode interception at the same time.

-## 运行模式
+## Runtime Modes

-### APP 模式
+### App Mode

-适用于：
+Suitable for:

- 只使用 Wi-Fi 的设备测试；
- 不依赖第三方代理客户端的本地验证；
- 需要在 App 内完成代理、证书和环境检测的场景。
+- Wi-Fi-only device testing;
+- Local testing without a third-party proxy client;
+- Workflows that need in-app proxy, certificate, and environment guidance.

-使用条件：
+Requirements:

- iOS 设备；
- 当前 Wi-Fi 支持手动 HTTP 代理；
- 安装并信任本机 CA；
- 在 App 内完成代理配置和环境检测。
+- An iOS device;
+- A Wi-Fi network that permits manual HTTP proxy configuration;
+- Installation and trust of the local CA;
+- Completion of the in-app proxy and environment checks.

-### 第三方代理模式
+### Third-party Proxy Mode

-适用于：
+Suitable for:

- 需要 Wi-Fi、4G 或 5G 网络覆盖的测试；
- 已经使用支持模块或脚本的代理客户端；
- 希望由第三方客户端继续保持代理配置的场景。
+- Tests that need Wi-Fi, 4G, or 5G coverage;
+- Existing supported proxy-client workflows;
+- Cases where the third-party client should keep the proxy configuration active.

-当前客户端状态：
+Current client status:

-| 客户端 | 状态 | 社区配置 |
+| Client | Status | Community configuration |
 |---|---|---|
-| Shadowrocket | 当前用于真机测试 | App 内置教程 |
-| Surge | 已提供配置，尚未完整验证 | 待征集 |
-| Quantumult X | 已提供配置，尚未完整验证 | 待征集 |
-| Loon | 已提供配置，尚未完整验证 | 待征集 |
-| Stash | 已提供配置，尚未完整验证 | 待征集 |
-| Egern | 使用 Surge 模块，尚未完整验证 | 待征集 |
+| Shadowrocket | Currently used for on-device testing | Built-in App guide |
+| Surge | Configuration provided, not fully verified | Contributions wanted |
+| Quantumult X | Configuration provided, not fully verified | Contributions wanted |
+| Loon | Configuration provided, not fully verified | Contributions wanted |
+| Stash | Configuration provided, not fully verified | Contributions wanted |
+| Egern | Uses the Surge module, not fully verified | Contributions wanted |

-社区配置按客户端分区审核；采纳后会在上表链接教程和投稿者，投稿者也可以选择匿名收录。
+Community configurations are reviewed by client. Accepted submissions are linked in this table with attribution unless
+the contributor requests anonymous inclusion.

-模块与脚本现由本仓库托管，原 `Yu9191/wloc` 仓库已删除，仅保留来源致谢，不再作为运行时依赖：
+Modules and scripts are now hosted by this repository. The original
+`Yu9191/wloc` repository was deleted and remains attribution only, not a runtime dependency:

- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
+- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)

-第三方客户端、证书、MITM 和代理开关由客户端自身负责。导入任何第三方模块前，请先审查其配置和脚本内容。
+The selected client owns its certificates, MITM configuration, and proxy switches. Review third-party modules and
+scripts before importing them.

-## 快速开始
+## Quick Start

-### 1. 安装应用
+### 1. Install the App

-你可以使用：
+You can use:

- 自己的 Apple Developer 签名环境；
- 适合个人测试的自签工具；
- 项目 Releases 中的未签名 IPA；
- 在 macOS 上按[构建说明](docs/BUILD.md)自行构建。
+- Your own Apple Developer signing environment;
+- A self-signing tool suitable for personal testing;
+- The unsigned IPA published in Releases;
+- A source build produced on macOS using the [build guide](docs/BUILD.md).

-免费自签环境可能无法使用 Network Extension，因此 APP 模式采用设备内本地代理和 Wi-Fi 手动代理，不依赖
-VPN 组件。
+Free self-signing environments may not provide Network Extension capabilities. App Mode therefore uses an on-device
+proxy plus a manual Wi-Fi HTTP proxy and does not depend on a VPN component.

-#### 自签安装说明
+#### Self-Signing Instructions

-Release 附件是未签名 IPA，需要使用自签工具安装到 iPhone：
+Release assets are unsigned IPA files and must be installed on an iPhone with a self-signing tool:

-1. **开启自签支持**：iOS 16 及以上版本前往“设置 → 隐私与安全性 → 开发者模式”，开启后按系统提示重启并
-   确认；iOS 15 没有此开关，可跳过本步。
-2. **下载 IPA**：前往本项目的 [Releases](https://github.com/xweiba/location-spoofer/releases)，下载最新的
-   `PaopaoLocationSpoofer-unsigned.ipa`。
-3. **准备自签软件**：前往 [Impactor Releases](https://github.com/claration/Impactor/releases) 下载对应系统
-   版本的 Impactor；也可以使用爱思助手等支持 IPA 自签安装的软件。
-4. **连接并安装**：使用 USB 数据线连接 iPhone 与电脑，在手机上选择“信任此电脑”，然后在自签软件中选择
-   刚下载的 IPA，根据软件提示完成签名与安装。
+1. **Enable sideloading support**: On iOS 16 or newer, open Settings → Privacy & Security → Developer Mode, enable it,
+   then restart and confirm when prompted. iOS 15 does not have this switch, so skip this step.
+2. **Download the IPA**: Open this project's [Releases](https://github.com/xweiba/location-spoofer/releases) and download
+   the latest `PaopaoLocationSpoofer-unsigned.ipa`.
+3. **Prepare signing software**: Download the appropriate Impactor build from
+   [Impactor Releases](https://github.com/claration/Impactor/releases). Other tools that support self-signing and installing
+   IPA files, such as Aisi Assistant, may also be used.
+4. **Connect and install**: Connect the iPhone to the computer with a USB cable, choose “Trust This Computer” on the
+   phone, select the downloaded IPA in the signing software, and follow that tool's instructions to sign and install it.

-Impactor 支持 Windows、macOS 和 Linux；Windows 若无法识别设备，请先安装 iTunes 提供的 Apple 设备驱动。
-爱思助手属于第三方软件，请从其官方渠道获取，并自行评估账号、证书和隐私风险。
+Impactor supports Windows, macOS, and Linux. If Windows cannot detect the device, install the Apple device drivers supplied
+with iTunes first. Aisi Assistant is third-party software; obtain it from its official channel and evaluate its account,
+certificate, and privacy risks yourself.

-安装完成后，若 iOS 阻止打开 App，请前往“设置 → 通用 → VPN 与设备管理”信任对应的开发者 App。免费
-Apple ID 自签通常只有 7 天有效期，到期后需要重新签名安装。
+After installation, if iOS blocks the app from opening, go to Settings → General → VPN & Device Management and trust the
+corresponding developer app. A free Apple ID signature normally expires after seven days and must then be renewed.

-### 2. 首次启动
+### 2. First Launch

-首次启动时：
+1. Choose App Mode or Third-party Proxy Mode;
+2. Complete the corresponding in-app setup;
+3. Run the environment check;
+4. Search, tap, or drag on the map to select a test location;
+5. Enable the test location and verify the result in the authorized test environment.

-1. 选择 APP 模式或第三方代理模式；
-2. 按照 App 内引导完成对应配置；
-3. 执行环境检测；
-4. 在地图中搜索、点击或拖动选择测试位置；
-5. 启用测试位置并在目标测试环境中验证结果。
+### 3. Restore the Real Location

-### 3. 恢复真实位置
+App Mode:

-APP 模式：
+1. Stop the test location;
+2. Disable the manual HTTP proxy on the current Wi-Fi network;
+3. Follow the in-app instructions to refresh the location environment.

-1. 停止测试位置；
-2. 关闭当前 Wi-Fi 的手动 HTTP 代理；
-3. 按 App 内提示刷新定位环境。
+Third-party Proxy Mode:

-第三方代理模式：
+1. Clear the WLOC coordinates from the app;
+2. Disable the corresponding module or proxy in the third-party client;
+3. Restore HTTPS decryption and proxy settings according to the client documentation.

-1. 使用 App 清除 WLOC 坐标；
-2. 在第三方客户端中关闭对应模块或代理；
-3. 按客户端要求恢复 HTTPS 解密和代理设置。
+Location caches may take time to refresh. Restart the device if the system or target app continues to show an old
+location.

-如果系统或目标应用仍显示旧位置，可能需要等待定位缓存刷新，必要时重启设备后再次验证。
+## Coordinate Handling

-## 坐标处理
+The project stores two coordinate representations:

-项目内部保存两种坐标表示：
+- WGS-84: the international standard used for WLOC writes;
+- GCJ-02: the domestic map representation used where required.

- WGS-84：国际标准，WLOC 写入使用此坐标；
- GCJ-02：国内地图标准，用于需要国内地图坐标的场景。
+MapKit does not expose a public API that reports whether its current runtime output uses GCJ-02 or WGS-84. The project
+uses a fixed-anchor query to resolve the active representation and performs controlled refreshes after blue-dot changes
+and explicit user actions.

-MapKit 不提供公开 API 直接返回当前是否使用 GCJ-02 或 WGS-84。项目通过固定锚点查询判断 MapKit 当前返回
-标准，并在运行期间根据蓝点变化和用户操作进行受控刷新。
+Each write boundary stores a complete WGS-84/GCJ-02 pair. Rendering selects the field matching the confirmed map
+representation instead of repeatedly converting an already typed value.

-坐标写入边界会保存完整的 WGS-84 / GCJ-02 坐标对，使用时根据当前地图标准选择对应字段，避免重复转换造成
-位置偏移。
-
-## 项目结构
+## Project Structure

 ```text
-App/        SwiftUI 界面、MapKit、定位和运行流程
-Core/       Go 代理、证书服务和定位响应处理
-Shared/     坐标、收藏、日志、配置和共享模型
-Resources/  Info.plist、Entitlements 和资源文件
-Config/     构建配置
-Scripts/    构建、打包和验证脚本
-Tests/      XCTest 和 Shell contract tests
-docs/       构建、模块和版本文档
+App/        SwiftUI interface, MapKit, location, and runtime flow
+Core/       Go proxy, certificate server, and location-response handling
+Shared/     Coordinates, favorites, logs, configuration, and shared models
+Resources/  Info.plist, Entitlements, and resources
+Config/     Build configuration
+Scripts/    Build, packaging, and validation scripts
+Tests/      XCTest and Shell contract tests
+docs/       Build, module, and release documentation
 ```

-## 构建项目
+## Building the Project

-源码构建需要 macOS 环境：
+Source builds require:

- macOS；
- Xcode；
- Xcode Command Line Tools；
- XcodeGen；
- Go 1.23 或更高版本。
+- macOS;
+- Xcode;
+- Xcode Command Line Tools;
+- XcodeGen;
+- Go 1.23 or newer.

-当前项目不支持在 Windows 上直接构建 iOS 应用。
+Building the iOS app directly on Windows is not supported.

 ```bash
 git clone https://github.com/xweiba/location-spoofer.git
@@ -329,119 +343,128 @@ cd location-spoofer
 ./build.sh
 ```

-运行构建并执行 Simulator 测试：
+Build and run Simulator tests:

 ```bash
 ./build.sh --test
 ```

-构建脚本会生成未签名 IPA：
+The build script generates an unsigned IPA:

 ```text
 dist/PaopaoLocationSpoofer-unsigned.ipa
 ```

-之后需要使用你自己的签名和安装流程部署到测试设备。
+Deploy it to a test device using your own signing and installation process.

-## 隐私与安全边界
+## Privacy and Security Boundaries

- 项目不包含遥测或远程控制服务；
- 项目不会自动上传用户位置数据；
- 运行日志保存在设备 App Group 容器中，并自动保留近三天；
- 问题报告需要用户主动复制后提交到 GitHub；
- APP 模式会访问本机代理和环境验证地址；
- 第三方代理模式可能访问本仓库托管的模块地址和 WLOC 配置接口；
- App 生成的 CA 私钥保存在设备 Keychain 中；
- 第三方客户端模块、MITM 和证书链路由用户选择的客户端负责。
+- The project contains no telemetry or remote-control service;
+- The project does not automatically upload location data;
+- Runtime logs remain in the device App Group container and retain only the latest three days;
+- Issue reports are copied by the user before being submitted to GitHub;
+- App Mode accesses the local proxy and the environment-verification URL;
+- Third-party Proxy Mode may access module URLs hosted by this repository and the WLOC configuration endpoint;
+- The CA private key generated by the app is stored in the device Keychain;
+- Third-party MITM, certificates, and proxy behavior are owned by the selected client.

-请不要把真实位置、认证信息、证书私钥或完整敏感日志提交到公开 Issue。
+Do not post real locations, authentication information, CA private keys, or complete sensitive logs in public issues.

-## 限制
+## Limitations

- iOS 系统版本变化可能影响定位服务行为；
- MapKit 的坐标返回标准可能随系统、地区和定位环境变化；
- 系统定位存在缓存，切换位置后不一定立即生效；
- 第三方代理客户端的兼容性和规则行为需要分别验证；
- 不保证所有应用都使用同一种定位 API；
- 不保证所有应用或服务都接受测试坐标；
- 不保证在所有网络环境、设备型号和 iOS 版本上表现一致。
+- iOS updates may change location-service behavior;
+- MapKit coordinate output can vary with the system, region, and location environment;
+- System location caches may delay visible changes;
+- Each third-party proxy client requires separate compatibility testing;
+- Not every app uses the same location API;
+- Not every app or service accepts test coordinates;
+- Behavior is not guaranteed across every network, device model, or iOS version.

-## 贡献
+## License

-欢迎提交：
+The project code is distributed under the [GNU Affero General Public License v3.0](LICENSE).
+Third-party WLOC scripts retain their original copyright notices and AGPL-3.0 license in
+[`ThirdParty/WlocScripts/`](ThirdParty/WlocScripts/THIRD_PARTY_NOTICES.md).
+Other third-party dependencies remain subject to their respective licenses.

- [Bug Report](https://github.com/xweiba/location-spoofer/issues/new?template=bug-report.yml)；
- [功能建议](https://github.com/xweiba/location-spoofer/discussions/categories/%E5%8A%9F%E8%83%BD%E5%BB%BA%E8%AE%AE)；
- [使用帮助与兼容性测试](https://github.com/xweiba/location-spoofer/discussions/categories/%E4%BD%BF%E7%94%A8%E5%B8%AE%E5%8A%A9)；
- [第三方客户端配置和脱敏原始截图](https://github.com/xweiba/location-spoofer/discussions/categories/%E7%AC%AC%E4%B8%89%E6%96%B9%E9%85%8D%E7%BD%AE%E5%88%86%E4%BA%AB)；
- 性能改进；
- 文档改进；
- 测试补充。
+## Contributing

-提交 Bug 时建议优先通过 App 的“设置 → 支持 → 报告 Bug”生成报告。报告包含：
+Contributions are welcome for:

- iOS 版本；
- App 版本；
- 使用的运行模式；
- 当前第三方客户端；
- 是否可以稳定复现；
- 问题描述；
- 脱敏后的运行日志；
+- [Bug reports](https://github.com/xweiba/location-spoofer/issues/new?template=bug-report.yml);
+- [Feature requests](https://github.com/xweiba/location-spoofer/discussions/categories/%E5%8A%9F%E8%83%BD%E5%BB%BA%E8%AE%AE);
+- [Usage help and compatibility results](https://github.com/xweiba/location-spoofer/discussions/categories/%E4%BD%BF%E7%94%A8%E5%B8%AE%E5%8A%A9);
+- [Third-party client configurations and sanitized screenshots](https://github.com/xweiba/location-spoofer/discussions/categories/%E7%AC%AC%E4%B8%89%E6%96%B9%E9%85%8D%E7%BD%AE%E5%88%86%E4%BA%AB);
+- Performance improvements;
+- Documentation improvements;
+- Additional tests.

-GitHub Issue Form 中的“App 生成的诊断报告”字段与 App 复制内容一一对应。
+For bugs, generate a report from **Settings → Support → Report Bug** in the App whenever possible. The report includes:

-## 文档
+- iOS version;
+- App version;
+- Runtime mode;
+- Selected third-party client;
+- Whether the issue is reproducible;
+- Problem description;
+- Sanitized runtime logs;

- [构建说明](docs/BUILD.md)
- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
- [社区客户端教程与截图提交](docs/COMMUNITY_TUTORIALS.md)
- [更新日志](docs/CHANGELOG.md)
- [英文文档](README.en.md)
+Paste it into the **App-generated diagnostic report** field in the GitHub Issue Form.
+
+## Documentation
+
+- [Build guide](docs/BUILD.md)
+- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
+- [Changelog](docs/CHANGELOG.md)
+- [中文文档](README.zh-CN.md)
 - [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)

-## 功能预览
+## Feature Preview

-以下截图用于展示主界面和部分真机测试场景。实际结果会受到 iOS 版本、网络环境、系统缓存和目标应用定位策略
-影响，不代表对所有应用或版本作出兼容性保证。
+These screenshots show the main interface and selected on-device test scenarios. Actual results depend on the iOS
+version, network environment, system caches, and the target app's location strategy; they are not a compatibility
+guarantee for every app or release.

 <table>
  <tr>
-    <th>应用主界面</th>
-    <th>Apple 地图测试</th>
-    <th>高德地图测试</th>
+    <th>Main interface</th>
+    <th>Apple Maps test</th>
+    <th>Amap test</th>
  </tr>
  <tr>
-    <td><img src="images/主界面.jpg" alt="Location Spoofer 地图选点主界面" width="220"></td>
-    <td><img src="images/Apple%20Map.jpg" alt="Apple 地图定位测试场景" width="220"></td>
-    <td><img src="images/高德地图.jpg" alt="高德地图定位测试场景" width="220"></td>
+    <td><img src="images/主界面.jpg" alt="Location Spoofer map selection interface" width="220"></td>
+    <td><img src="images/Apple%20Map.jpg" alt="Apple Maps location test scenario" width="220"></td>
+    <td><img src="images/高德地图.jpg" alt="Amap location test scenario" width="220"></td>
  </tr>
  <tr>
-    <th>微信测试</th>
-    <th>钉钉测试</th>
-    <th>Apple Watch 场景测试</th>
+    <th>WeChat test</th>
+    <th>DingTalk test</th>
+    <th>Apple Watch scenario test</th>
  </tr>
  <tr>
-    <td><img src="images/微信.jpg" alt="微信定位测试场景" width="220"></td>
-    <td><img src="images/钉钉.jpg" alt="钉钉定位测试场景" width="220"></td>
-    <td><img src="images/高血压.jpg" alt="Apple Watch 地区功能测试场景" width="220"></td>
+    <td><img src="images/微信.jpg" alt="WeChat location test scenario" width="220"></td>
+    <td><img src="images/钉钉.jpg" alt="DingTalk location test scenario" width="220"></td>
+    <td><img src="images/高血压.jpg" alt="Apple Watch region-feature test scenario" width="220"></td>
  </tr>
 </table>

-## 致谢与友链
+## Acknowledgements and Links

-核心定位响应处理思路、Go 实现和第三方模块参考自（`Yu9191/wloc` 原仓库已删除）：
+The core location-response handling approach, Go implementation, and third-party modules are based on
+the following projects (`Yu9191/wloc` has since been deleted):

 - [Yu9191/wloc](https://github.com/Yu9191/wloc)
 - [ios-location-spoofer](https://github.com/mekos2772/ios-location-spoofer)

-感谢以下 LINUX DO 用户对项目的贡献：
+Thanks to the following LINUX DO users for their contributions:

- 功能修复：[陈泽](https://linux.do/u/lixiaobaivv)
- 思路及建议：[Alex](https://linux.do/u/_alex)、[ye4241](https://linux.do/u/ye4241)
+- Bug fixes: [Chen Ze](https://linux.do/u/lixiaobaivv)
+- Ideas and suggestions: [Alex](https://linux.do/u/_alex), [ye4241](https://linux.do/u/ye4241)

-友链：
+Links:

 - [LINUX DO](https://linux.do/)
 - [iOS-Location-Spoofer-Web](https://github.com/akudamatata/iOS-Location-Spoofer-Web)

-感谢开源社区中参与 iOS 定位服务研究、网络代理和移动端测试工具建设的贡献者。
+Thanks to the open-source contributors working on iOS location-service research, network proxies, and mobile testing
+tools.