From ded650a73df33d16e3ad7cd591639d34e8288c01 Mon Sep 17 00:00:00 2001 From: feijie Date: Tue, 10 Dec 2024 22:20:06 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=B7=BB=E5=8A=A0=E4=BD=8D?= =?UTF-8?q?=E7=BD=AE=E6=A8=A1=E5=9D=97=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../LINGYUN.Abp.Location.Baidu/README.EN.md | 137 +++++++++++++++++ .../LINGYUN.Abp.Location.Baidu/README.md | 137 +++++++++++++++++ .../LINGYUN.Abp.Location.Tencent/README.EN.md | 144 ++++++++++++++++++ .../LINGYUN.Abp.Location.Tencent/README.md | 144 ++++++++++++++++++ .../common/LINGYUN.Abp.Location/README.EN.md | 70 ++++++++- .../common/LINGYUN.Abp.Location/README.md | 66 +++++--- .../README.EN.md | 86 +++++++++++ .../README.md | 86 +++++++++++ .../README.EN.md | 93 +++++++++++ .../README.md | 104 +++++++++---- .../README.EN.md | 129 ++++++++++++++++ .../README.md | 139 +++++++++++++---- .../LINGYUN.Abp.Localization.Xml/README.EN.md | 102 +++++++++++++ .../LINGYUN.Abp.Localization.Xml/README.md | 116 +++++++++----- 14 files changed, 1427 insertions(+), 126 deletions(-) create mode 100644 aspnet-core/framework/common/LINGYUN.Abp.Location.Baidu/README.EN.md create mode 100644 aspnet-core/framework/common/LINGYUN.Abp.Location.Baidu/README.md create mode 100644 aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/README.EN.md create mode 100644 aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/README.md create mode 100644 aspnet-core/framework/localization/LINGYUN.Abp.AspNetCore.Mvc.Localization/README.EN.md create mode 100644 aspnet-core/framework/localization/LINGYUN.Abp.AspNetCore.Mvc.Localization/README.md create mode 100644 aspnet-core/framework/localization/LINGYUN.Abp.Localization.CultureMap/README.EN.md create mode 100644 aspnet-core/framework/localization/LINGYUN.Abp.Localization.Persistence/README.EN.md create mode 100644 aspnet-core/framework/localization/LINGYUN.Abp.Localization.Xml/README.EN.md diff --git a/aspnet-core/framework/common/LINGYUN.Abp.Location.Baidu/README.EN.md b/aspnet-core/framework/common/LINGYUN.Abp.Location.Baidu/README.EN.md new file mode 100644 index 000000000..2e59e5e26 --- /dev/null +++ b/aspnet-core/framework/common/LINGYUN.Abp.Location.Baidu/README.EN.md @@ -0,0 +1,137 @@ +# LINGYUN.Abp.Location.Baidu + +## Introduction + +`LINGYUN.Abp.Location.Baidu` is a location service implementation module based on Baidu Maps API, providing functionalities such as geocoding, reverse geocoding, IP location, and more. + +## Features + +* Geocoding: Convert structured addresses into latitude and longitude coordinates +* Reverse Geocoding: Convert coordinates into structured addresses +* IP Location: Get location information based on IP addresses +* POI (Points of Interest) Information: Get information about nearby businesses, restaurants, and other points of interest +* Road Information: Get information about nearby roads +* Administrative Region Information: Get detailed administrative region hierarchy information + +## Installation + +```bash +dotnet add package LINGYUN.Abp.Location.Baidu +``` + +## Configuration + +1. Add module dependency: + +```csharp +[DependsOn(typeof(AbpBaiduLocationModule))] +public class YourModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + // Set Baidu Maps API key + options.AccessKey = "your-baidu-map-ak"; + // Optional: Set security key (for sn verification) + options.SecurityKey = "your-baidu-map-sk"; + // Optional: Set coordinate system type (default is bd09ll) + options.CoordType = "bd09ll"; + // Optional: Set output format (default is json) + options.Output = "json"; + }); + } +} +``` + +## Usage + +1. Inject and use the location resolution service: + +```csharp +public class YourLocationService +{ + private readonly ILocationResolveProvider _locationProvider; + + public YourLocationService(ILocationResolveProvider locationProvider) + { + _locationProvider = locationProvider; + } + + // Geocoding: Convert address to coordinates + public async Task GeocodeAsync(string address) + { + // city parameter is optional, used to specify the city of the address + return await _locationProvider.GeocodeAsync(address, "Beijing"); + } + + // Reverse Geocoding: Convert coordinates to address + public async Task ReGeocodeAsync(double lat, double lng) + { + // radius parameter is optional, specifies search radius (in meters) + return await _locationProvider.ReGeocodeAsync(lat, lng, 1000); + } + + // IP Geolocation + public async Task IPGeocodeAsync(string ipAddress) + { + return await _locationProvider.IPGeocodeAsync(ipAddress); + } +} +``` + +## Response Data Description + +### Geocoding Response Data + +```json +{ + "location": { + "lat": 39.915119, // Latitude value + "lng": 116.403963 // Longitude value + }, + "precise": 1, // Additional location info, precise match or not (1 for precise, 0 for not precise) + "confidence": 80, // Confidence level + "comprehension": 100, // Address understanding level + "level": "门址" // Address type +} +``` + +### Reverse Geocoding Response Data + +```json +{ + "location": { + "lat": 39.915119, // Latitude value + "lng": 116.403963 // Longitude value + }, + "formatted_address": "Dongchangan Street, Dongcheng District, Beijing", // Structured address + "business": "Tiananmen", // Business area information + "addressComponent": { + "country": "China", // Country + "province": "Beijing", // Province + "city": "Beijing", // City + "district": "Dongcheng District", // District + "street": "Dongchangan Street", // Street + "street_number": "1" // Street number + }, + "pois": [ // Nearby POIs + { + "name": "Tiananmen", // POI name + "type": "Tourist Attraction", // POI type + "distance": "100" // Distance (meters) + } + ], + "roads": [ // Nearby roads + { + "name": "Dongchangan Street", // Road name + "distance": "50" // Distance (meters) + } + ] +} +``` + +## More Information + +* [中文文档](./README.md) +* [Baidu Maps Open Platform](https://lbsyun.baidu.com/) diff --git a/aspnet-core/framework/common/LINGYUN.Abp.Location.Baidu/README.md b/aspnet-core/framework/common/LINGYUN.Abp.Location.Baidu/README.md new file mode 100644 index 000000000..0fcc51411 --- /dev/null +++ b/aspnet-core/framework/common/LINGYUN.Abp.Location.Baidu/README.md @@ -0,0 +1,137 @@ +# LINGYUN.Abp.Location.Baidu + +## 介绍 + +`LINGYUN.Abp.Location.Baidu` 是基于百度地图API的位置服务实现模块，提供了地理编码、反向地理编码、IP定位等功能。 + +## 功能特性 + +* 地理编码：将详细的结构化地址转换为对应的经纬度坐标 +* 反向地理编码：将经纬度坐标转换为对应的结构化地址 +* IP定位：根据IP地址获取位置信息 +* POI（兴趣点）信息：获取周边的商铺、餐厅等兴趣点信息 +* 道路信息：获取附近的道路信息 +* 行政区划信息：获取详细的行政区划层级信息 + +## 安装 + +```bash +dotnet add package LINGYUN.Abp.Location.Baidu +``` + +## 配置 + +1. 添加模块依赖： + +```csharp +[DependsOn(typeof(AbpBaiduLocationModule))] +public class YourModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + // 设置百度地图API密钥 + options.AccessKey = "your-baidu-map-ak"; + // 可选：设置安全密钥（sn校验） + options.SecurityKey = "your-baidu-map-sk"; + // 可选：设置坐标系类型（默认为bd09ll） + options.CoordType = "bd09ll"; + // 可选：设置输出格式（默认为json） + options.Output = "json"; + }); + } +} +``` + +## 使用方法 + +1. 注入并使用位置解析服务： + +```csharp +public class YourLocationService +{ + private readonly ILocationResolveProvider _locationProvider; + + public YourLocationService(ILocationResolveProvider locationProvider) + { + _locationProvider = locationProvider; + } + + // 地理编码：地址转坐标 + public async Task GeocodeAsync(string address) + { + // city参数可选，用于指定地址所在城市 + return await _locationProvider.GeocodeAsync(address, "北京市"); + } + + // 反向地理编码：坐标转地址 + public async Task ReGeocodeAsync(double lat, double lng) + { + // radius参数可选，指定搜索半径（米） + return await _locationProvider.ReGeocodeAsync(lat, lng, 1000); + } + + // IP地理位置解析 + public async Task IPGeocodeAsync(string ipAddress) + { + return await _locationProvider.IPGeocodeAsync(ipAddress); + } +} +``` + +## 返回数据说明 + +### 地理编码返回数据 + +```json +{ + "location": { + "lat": 39.915119, // 纬度值 + "lng": 116.403963 // 经度值 + }, + "precise": 1, // 位置的附加信息，是否精确查找（1为精确，0为不精确） + "confidence": 80, // 可信度 + "comprehension": 100, // 地址理解程度 + "level": "门址" // 地址类型 +} +``` + +### 反向地理编码返回数据 + +```json +{ + "location": { + "lat": 39.915119, // 纬度值 + "lng": 116.403963 // 经度值 + }, + "formatted_address": "北京市东城区东长安街", // 结构化地址信息 + "business": "天安门", // 商圈信息 + "addressComponent": { + "country": "中国", // 国家 + "province": "北京市", // 省份 + "city": "北京市", // 城市 + "district": "东城区", // 区县 + "street": "东长安街", // 街道 + "street_number": "1号" // 门牌号 + }, + "pois": [ // 周边POI信息 + { + "name": "天安门", // POI名称 + "type": "旅游景点", // POI类型 + "distance": "100" // 距离（米） + } + ], + "roads": [ // 周边道路信息 + { + "name": "东长安街", // 道路名称 + "distance": "50" // 距离（米） + } + ] +} +``` + +## 更多信息 + +* [English Documentation](./README.EN.md) +* [百度地图开放平台](https://lbsyun.baidu.com/) diff --git a/aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/README.EN.md b/aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/README.EN.md new file mode 100644 index 000000000..d05ee909e --- /dev/null +++ b/aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/README.EN.md @@ -0,0 +1,144 @@ +# LINGYUN.Abp.Location.Tencent + +## Introduction + +`LINGYUN.Abp.Location.Tencent` is a location service implementation module based on Tencent Maps API, providing functionalities such as geocoding, reverse geocoding, IP location, and more. + +## Features + +* Geocoding: Convert structured addresses into latitude and longitude coordinates +* Reverse Geocoding: Convert coordinates into structured addresses +* IP Location: Get location information based on IP addresses +* POI (Points of Interest) Information: Get information about nearby businesses, restaurants, and other points of interest +* Administrative Region Information: Get detailed administrative region hierarchy information +* Address Parsing: Intelligent address parsing supporting multiple formats + +## Installation + +```bash +dotnet add package LINGYUN.Abp.Location.Tencent +``` + +## Configuration + +1. Add module dependency: + +```csharp +[DependsOn(typeof(AbpTencentLocationModule))] +public class YourModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + // Set Tencent Maps API key + options.Key = "your-tencent-map-key"; + // Optional: Set security key (for SK verification) + options.SecretKey = "your-tencent-map-sk"; + }); + } +} +``` + +## Usage + +1. Inject and use the location resolution service: + +```csharp +public class YourLocationService +{ + private readonly ILocationResolveProvider _locationProvider; + + public YourLocationService(ILocationResolveProvider locationProvider) + { + _locationProvider = locationProvider; + } + + // Geocoding: Convert address to coordinates + public async Task GeocodeAsync(string address) + { + // city parameter is optional, used to specify the city of the address + return await _locationProvider.GeocodeAsync(address, "Beijing"); + } + + // Reverse Geocoding: Convert coordinates to address + public async Task ReGeocodeAsync(double lat, double lng) + { + // radius parameter is optional, specifies search radius (in meters) + return await _locationProvider.ReGeocodeAsync(lat, lng, 1000); + } + + // IP Geolocation + public async Task IPGeocodeAsync(string ipAddress) + { + return await _locationProvider.IPGeocodeAsync(ipAddress); + } +} +``` + +## Response Data Description + +### Geocoding Response Data + +```json +{ + "location": { + "lat": 39.915119, // Latitude value + "lng": 116.403963 // Longitude value + }, + "title": "Tiananmen", // Place name + "address": "Dongchangan Street, Dongcheng District, Beijing", // Address + "category": "Tourist Attraction", // Category + "adcode": "110101", // Administrative region code + "similarity": 0.8, // Similarity (0-1) + "reliability": 7, // Reliability (1-10) + "level": 11 // Address type +} +``` + +### Reverse Geocoding Response Data + +```json +{ + "location": { + "lat": 39.915119, // Latitude value + "lng": 116.403963 // Longitude value + }, + "address": "Dongchangan Street, Dongcheng District, Beijing", // Complete address + "formatted_addresses": { + "recommend": "Tiananmen, Dongcheng District", // Recommended address + "rough": "Dongcheng District, Beijing" // Rough address + }, + "address_component": { + "nation": "China", // Country + "province": "Beijing", // Province + "city": "Beijing", // City + "district": "Dongcheng District", // District + "street": "Dongchangan Street", // Street + "street_number": "1" // Street number + }, + "pois": [ // Nearby POIs + { + "title": "Tiananmen", // POI name + "address": "Dongchangan Street, Dongcheng District, Beijing", // POI address + "category": "Tourist Attraction", // POI type + "distance": 100, // Distance (meters) + "_distance": 100.0, // Distance (meters, float) + "tel": "", // Phone number + "ad_info": { // Administrative region info + "adcode": "110101", // Administrative region code + "name": "Dongcheng District", // Administrative region name + "location": { // Administrative region center point + "lat": 39.915119, + "lng": 116.403963 + } + } + } + ] +} +``` + +## More Information + +* [中文文档](./README.md) +* [Tencent Location Service](https://lbs.qq.com/) diff --git a/aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/README.md b/aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/README.md new file mode 100644 index 000000000..384e1b4cd --- /dev/null +++ b/aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/README.md @@ -0,0 +1,144 @@ +# LINGYUN.Abp.Location.Tencent + +## 介绍 + +`LINGYUN.Abp.Location.Tencent` 是基于腾讯地图API的位置服务实现模块，提供了地理编码、反向地理编码、IP定位等功能。 + +## 功能特性 + +* 地理编码：将详细的结构化地址转换为对应的经纬度坐标 +* 反向地理编码：将经纬度坐标转换为对应的结构化地址 +* IP定位：根据IP地址获取位置信息 +* POI（兴趣点）信息：获取周边的商铺、餐厅等兴趣点信息 +* 行政区划信息：获取详细的行政区划层级信息 +* 地址解析：智能解析地址信息，支持多种格式 + +## 安装 + +```bash +dotnet add package LINGYUN.Abp.Location.Tencent +``` + +## 配置 + +1. 添加模块依赖： + +```csharp +[DependsOn(typeof(AbpTencentLocationModule))] +public class YourModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + // 设置腾讯地图API密钥 + options.Key = "your-tencent-map-key"; + // 可选：设置安全密钥（SK校验） + options.SecretKey = "your-tencent-map-sk"; + }); + } +} +``` + +## 使用方法 + +1. 注入并使用位置解析服务： + +```csharp +public class YourLocationService +{ + private readonly ILocationResolveProvider _locationProvider; + + public YourLocationService(ILocationResolveProvider locationProvider) + { + _locationProvider = locationProvider; + } + + // 地理编码：地址转坐标 + public async Task GeocodeAsync(string address) + { + // city参数可选，用于指定地址所在城市 + return await _locationProvider.GeocodeAsync(address, "北京市"); + } + + // 反向地理编码：坐标转地址 + public async Task ReGeocodeAsync(double lat, double lng) + { + // radius参数可选，指定搜索半径（米） + return await _locationProvider.ReGeocodeAsync(lat, lng, 1000); + } + + // IP地理位置解析 + public async Task IPGeocodeAsync(string ipAddress) + { + return await _locationProvider.IPGeocodeAsync(ipAddress); + } +} +``` + +## 返回数据说明 + +### 地理编码返回数据 + +```json +{ + "location": { + "lat": 39.915119, // 纬度值 + "lng": 116.403963 // 经度值 + }, + "title": "天安门", // 地点名称 + "address": "北京市东城区东长安街", // 地址 + "category": "旅游景点", // 类别 + "adcode": "110101", // 行政区划代码 + "similarity": 0.8, // 相似度（0-1） + "reliability": 7, // 可信度（1-10） + "level": 11 // 地址类型 +} +``` + +### 反向地理编码返回数据 + +```json +{ + "location": { + "lat": 39.915119, // 纬度值 + "lng": 116.403963 // 经度值 + }, + "address": "北京市东城区东长安街", // 完整地址 + "formatted_addresses": { + "recommend": "东城区天安门", // 推荐地址 + "rough": "北京市东城区" // 粗略地址 + }, + "address_component": { + "nation": "中国", // 国家 + "province": "北京市", // 省份 + "city": "北京市", // 城市 + "district": "东城区", // 区县 + "street": "东长安街", // 街道 + "street_number": "1号" // 门牌号 + }, + "pois": [ // 周边POI信息 + { + "title": "天安门", // POI名称 + "address": "北京市东城区东长安街", // POI地址 + "category": "旅游景点", // POI类型 + "distance": 100, // 距离（米） + "_distance": 100.0, // 距离（米，浮点数） + "tel": "", // 电话 + "ad_info": { // 行政区划信息 + "adcode": "110101", // 行政区划代码 + "name": "东城区", // 行政区划名称 + "location": { // 行政区划中心点 + "lat": 39.915119, + "lng": 116.403963 + } + } + } + ] +} +``` + +## 更多信息 + +* [English Documentation](./README.EN.md) +* [腾讯位置服务](https://lbs.qq.com/) diff --git a/aspnet-core/framework/common/LINGYUN.Abp.Location/README.EN.md b/aspnet-core/framework/common/LINGYUN.Abp.Location/README.EN.md index 3c66cb2ec..56fd2eee6 100644 --- a/aspnet-core/framework/common/LINGYUN.Abp.Location/README.EN.md +++ b/aspnet-core/framework/common/LINGYUN.Abp.Location/README.EN.md @@ -7,6 +7,7 @@ ## Features * Geocoding and Reverse Geocoding +* IP Geolocation Resolution * Location distance calculation (based on Google algorithm, error <0.2m) * Location offset calculation * Support for POI (Points of Interest) and road information @@ -20,7 +21,7 @@ dotnet add package LINGYUN.Abp.Location ## Usage -1. Add `[DependsOn(typeof(AbpLocationModule))]` to your module class. +1. Add module dependency: ```csharp [DependsOn(typeof(AbpLocationModule))] @@ -42,15 +43,23 @@ public class YourLocationService _locationProvider = locationProvider; } + // Geocoding: Convert address to coordinates public async Task GeocodeAsync(string address) { return await _locationProvider.GeocodeAsync(address); } + // Reverse Geocoding: Convert coordinates to address public async Task ReGeocodeAsync(double lat, double lng) { return await _locationProvider.ReGeocodeAsync(lat, lng); } + + // IP Geolocation Resolution + public async Task IPGeocodeAsync(string ipAddress) + { + return await _locationProvider.IPGeocodeAsync(ipAddress); + } } ``` @@ -59,10 +68,15 @@ public class YourLocationService ### 1. Distance Calculation ```csharp -// Calculate distance between two locations +// Create location objects var location1 = new Location { Latitude = 39.9042, Longitude = 116.4074 }; // Beijing var location2 = new Location { Latitude = 31.2304, Longitude = 121.4737 }; // Shanghai -double distance = Location.CalcDistance(location1, location2); // Returns distance in meters + +// Calculate distance between two points (in meters) +double distance = location1.CalcDistance(location2); + +// Calculate location offset +var offset = location1.CalcOffset(1000, 45); // Offset 1000 meters to the northeast ``` ### 2. Calculate Location Offset Range @@ -78,18 +92,60 @@ var position = Location.CalcOffsetDistance(location, 1000); // 1km range ```csharp public class CustomLocationProvider : ILocationResolveProvider { - public async Task GeocodeAsync(string address) + public async Task IPGeocodeAsync(string ipAddress) { - // Implement geocoding logic + // Implement IP geolocation resolution } - public async Task ReGeocodeAsync(double lat, double lng) + public async Task GeocodeAsync(string address, string city = null) { - // Implement reverse geocoding logic + // Implement geocoding } + + public async Task ReGeocodeAsync(double lat, double lng, int radius = 50) + { + // Implement reverse geocoding + } +} +``` + +## Custom Location Resolution Provider Implementation + +To implement a custom location resolution provider: + +1. Implement the `ILocationResolveProvider` interface: + +```csharp +public class CustomLocationProvider : ILocationResolveProvider +{ + public async Task IPGeocodeAsync(string ipAddress) + { + // Implement IP geolocation resolution + } + + public async Task GeocodeAsync(string address, string city = null) + { + // Implement geocoding + } + + public async Task ReGeocodeAsync(double lat, double lng, int radius = 50) + { + // Implement reverse geocoding + } +} +``` + +2. Register your implementation in your module: + +```csharp +public override void ConfigureServices(ServiceConfigurationContext context) +{ + context.Services.AddTransient(); } ``` ## Links * [中文文档](./README.md) +* [Baidu Maps Location Service](./LINGYUN.Abp.Location.Baidu/README.EN.md) +* [Tencent Maps Location Service](./LINGYUN.Abp.Location.Tencent/README.EN.md) diff --git a/aspnet-core/framework/common/LINGYUN.Abp.Location/README.md b/aspnet-core/framework/common/LINGYUN.Abp.Location/README.md index fa8cf8d55..d5b587ee1 100644 --- a/aspnet-core/framework/common/LINGYUN.Abp.Location/README.md +++ b/aspnet-core/framework/common/LINGYUN.Abp.Location/README.md @@ -4,9 +4,10 @@ `LINGYUN.Abp.Location` 是一个位置服务基础模块，提供了地理位置相关的功能，包括地理编码（正向/反向）、距离计算等功能。 -## 功能 +## 功能特性 * 地理编码（Geocoding）和反向地理编码（Reverse Geocoding） +* IP地理位置解析 * 位置距离计算（基于Google算法，误差<0.2米） * 位置偏移量计算 * 支持POI（兴趣点）和道路信息 @@ -18,9 +19,9 @@ dotnet add package LINGYUN.Abp.Location ``` -## 使用 +## 使用方法 -1. 添加 `[DependsOn(typeof(AbpLocationModule))]` 到你的模块类上。 +1. 添加模块依赖： ```csharp [DependsOn(typeof(AbpLocationModule))] @@ -42,54 +43,79 @@ public class YourLocationService _locationProvider = locationProvider; } + // 地理编码：地址转坐标 public async Task GeocodeAsync(string address) { return await _locationProvider.GeocodeAsync(address); } + // 反向地理编码：坐标转地址 public async Task ReGeocodeAsync(double lat, double lng) { return await _locationProvider.ReGeocodeAsync(lat, lng); } + + // IP地理位置解析 + public async Task IPGeocodeAsync(string ipAddress) + { + return await _locationProvider.IPGeocodeAsync(ipAddress); + } } ``` -## 高级用法 +## 位置计算 -### 1. 距离计算 +模块提供了强大的位置计算功能： ```csharp -// 计算两个位置之间的距离 +// 创建位置对象 var location1 = new Location { Latitude = 39.9042, Longitude = 116.4074 }; // 北京 var location2 = new Location { Latitude = 31.2304, Longitude = 121.4737 }; // 上海 -double distance = Location.CalcDistance(location1, location2); // 返回单位：米 -``` -### 2. 计算位置偏移范围 +// 计算两点之间的距离（米） +double distance = location1.CalcDistance(location2); -```csharp -var location = new Location { Latitude = 39.9042, Longitude = 116.4074 }; -// 计算指定距离（米）的偏移范围 -var position = Location.CalcOffsetDistance(location, 1000); // 1公里范围 +// 计算位置的偏移 +var offset = location1.CalcOffset(1000, 45); // 向东北方向偏移1000米 ``` -### 3. 自定义位置解析提供程序 +## 自定义位置解析提供程序 + +要实现自定义的位置解析提供程序，需要： + +1. 实现 `ILocationResolveProvider` 接口： ```csharp public class CustomLocationProvider : ILocationResolveProvider { - public async Task GeocodeAsync(string address) + public async Task IPGeocodeAsync(string ipAddress) { - // 实现地理编码逻辑 + // 实现IP地理位置解析 } - public async Task ReGeocodeAsync(double lat, double lng) + public async Task GeocodeAsync(string address, string city = null) { - // 实现反向地理编码逻辑 + // 实现地理编码 } + + public async Task ReGeocodeAsync(double lat, double lng, int radius = 50) + { + // 实现反向地理编码 + } +} +``` + +2. 在模块中注册你的实现： + +```csharp +public override void ConfigureServices(ServiceConfigurationContext context) +{ + context.Services.AddTransient(); } ``` -## 链接 +## 更多信息 -* [English document](./README.EN.md) +* [English Documentation](./README.EN.md) +* [百度地图定位服务](./LINGYUN.Abp.Location.Baidu/README.md) +* [腾讯地图定位服务](./LINGYUN.Abp.Location.Tencent/README.md) diff --git a/aspnet-core/framework/localization/LINGYUN.Abp.AspNetCore.Mvc.Localization/README.EN.md b/aspnet-core/framework/localization/LINGYUN.Abp.AspNetCore.Mvc.Localization/README.EN.md new file mode 100644 index 000000000..6b5ff2d54 --- /dev/null +++ b/aspnet-core/framework/localization/LINGYUN.Abp.AspNetCore.Mvc.Localization/README.EN.md @@ -0,0 +1,86 @@ +# LINGYUN.Abp.AspNetCore.Mvc.Localization + +ABP framework localization management module, providing Web API interfaces for localization resources. + +## Features + +* Provides localization text management API interfaces +* Supports multi-language resource querying and comparison +* Supports filtering by resource name and culture name +* Supports integration of external localization resources +* Supports localization resource difference comparison + +## Installation + +```bash +dotnet add package LINGYUN.Abp.AspNetCore.Mvc.Localization +``` + +## Module Dependencies + +```csharp +[DependsOn(typeof(AbpAspNetCoreMvcLocalizationModule))] +public class YouProjectModule : AbpModule +{ + // other +} +``` + +## API Endpoints + +### Language Management + +* GET /api/localization/languages - Get all available languages +* GET /api/localization/languages/{cultureName} - Get specific language information + +### Resource Management + +* GET /api/localization/resources - Get all localization resources +* GET /api/localization/resources/{name} - Get specific localization resource + +### Text Management + +* GET /api/localization/texts - Get localization text list +* GET /api/localization/texts/by-key - Get localization text by key +* GET /api/localization/texts/differences - Get text differences between languages + +## Basic Usage + +1. Configure localization resources +```csharp +Configure(options => +{ + options.Resources + .Get() + .AddVirtualJson("/Your/Resource/Path"); +}); +``` + +2. Inject and use the service +```csharp +public class YourService +{ + private readonly ITextAppService _textAppService; + + public YourService(ITextAppService textAppService) + { + _textAppService = textAppService; + } + + public async Task GetLocalizedText(string key, string cultureName) + { + var text = await _textAppService.GetByCultureKeyAsync(new GetTextByKeyInput + { + Key = key, + CultureName = cultureName, + ResourceName = "YourResourceName" + }); + // Use the localized text + } +} +``` + +## More Information + +* [中文文档](./README.md) +* [ABP Localization Documentation](https://docs.abp.io/en/abp/latest/Localization) diff --git a/aspnet-core/framework/localization/LINGYUN.Abp.AspNetCore.Mvc.Localization/README.md b/aspnet-core/framework/localization/LINGYUN.Abp.AspNetCore.Mvc.Localization/README.md new file mode 100644 index 000000000..4b3c2fbba --- /dev/null +++ b/aspnet-core/framework/localization/LINGYUN.Abp.AspNetCore.Mvc.Localization/README.md @@ -0,0 +1,86 @@ +# LINGYUN.Abp.AspNetCore.Mvc.Localization + +ABP框架本地化管理模块，提供本地化资源的Web API接口。 + +## 功能特性 + +* 提供本地化文本管理API接口 +* 支持多语言资源的查询和比较 +* 支持按资源名称和文化名称过滤 +* 支持外部本地化资源的集成 +* 支持本地化资源的差异对比 + +## 安装 + +```bash +dotnet add package LINGYUN.Abp.AspNetCore.Mvc.Localization +``` + +## 模块依赖 + +```csharp +[DependsOn(typeof(AbpAspNetCoreMvcLocalizationModule))] +public class YouProjectModule : AbpModule +{ + // other +} +``` + +## API接口 + +### 语言管理 + +* GET /api/localization/languages - 获取所有可用语言 +* GET /api/localization/languages/{cultureName} - 获取指定语言信息 + +### 资源管理 + +* GET /api/localization/resources - 获取所有本地化资源 +* GET /api/localization/resources/{name} - 获取指定本地化资源 + +### 文本管理 + +* GET /api/localization/texts - 获取本地化文本列表 +* GET /api/localization/texts/by-key - 根据键获取本地化文本 +* GET /api/localization/texts/differences - 获取不同语言间的文本差异 + +## 基本用法 + +1. 配置本地化资源 +```csharp +Configure(options => +{ + options.Resources + .Get() + .AddVirtualJson("/Your/Resource/Path"); +}); +``` + +2. 注入并使用服务 +```csharp +public class YourService +{ + private readonly ITextAppService _textAppService; + + public YourService(ITextAppService textAppService) + { + _textAppService = textAppService; + } + + public async Task GetLocalizedText(string key, string cultureName) + { + var text = await _textAppService.GetByCultureKeyAsync(new GetTextByKeyInput + { + Key = key, + CultureName = cultureName, + ResourceName = "YourResourceName" + }); + // Use the localized text + } +} +``` + +## 更多信息 + +* [English Documentation](./README.EN.md) +* [ABP本地化文档](https://docs.abp.io/zh-Hans/abp/latest/Localization) diff --git a/aspnet-core/framework/localization/LINGYUN.Abp.Localization.CultureMap/README.EN.md b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.CultureMap/README.EN.md new file mode 100644 index 000000000..e0d61f886 --- /dev/null +++ b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.CultureMap/README.EN.md @@ -0,0 +1,93 @@ +# LINGYUN.Abp.Localization.CultureMap + +## Module Description + +This module solves localization issues with multiple culture format variants. It allows you to map different culture format identifiers to a standard format. + +Reference Project: [Owl.Abp.CultureMap](https://github.com/maliming/Owl.Abp.CultureMap) + +## Features + +* Support mapping multiple culture format identifiers to standard format +* Support independent mapping for Culture and UICulture +* Integration with ABP request localization +* Support custom culture mapping rules + +## Installation + +```bash +dotnet add package LINGYUN.Abp.Localization.CultureMap +``` + +## Base Modules + +* Volo.Abp.AspNetCore + +## Configuration + +The module provides the following configuration options: + +* CulturesMaps: List of culture mappings +* UiCulturesMaps: List of UI culture mappings + +Each mapping item contains: +* TargetCulture: Target culture identifier +* SourceCultures: List of source culture identifiers + +## Usage + +1. Add module dependency: + +```csharp +[DependsOn( + typeof(AbpLocalizationCultureMapModule))] +public class YouProjectModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + var zhHansCultureMapInfo = new CultureMapInfo + { + TargetCulture = "zh-Hans", + SourceCultures = new string[] { "zh", "zh_CN", "zh-CN" } + }; + + options.CulturesMaps.Add(zhHansCultureMapInfo); + options.UiCulturesMaps.Add(zhHansCultureMapInfo); + }); + } + + public override void OnApplicationInitialization(ApplicationInitializationContext context) + { + var app = context.GetApplicationBuilder(); + + app.UseMapRequestLocalization(); + } +} +``` + +## Common Use Cases + +1. Unify Simplified Chinese culture identifiers: +```csharp +options.CulturesMaps.Add(new CultureMapInfo +{ + TargetCulture = "zh-Hans", + SourceCultures = new string[] { "zh", "zh_CN", "zh-CN" } +}); +``` + +2. Unify Traditional Chinese culture identifiers: +```csharp +options.CulturesMaps.Add(new CultureMapInfo +{ + TargetCulture = "zh-Hant", + SourceCultures = new string[] { "zh_TW", "zh-TW", "zh_HK", "zh-HK" } +}); +``` + +## More Information + +* [中文文档](./README.md) +* [ABP Localization Documentation](https://docs.abp.io/en/abp/latest/Localization) diff --git a/aspnet-core/framework/localization/LINGYUN.Abp.Localization.CultureMap/README.md b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.CultureMap/README.md index 945c6cf07..aa7b2b2f4 100644 --- a/aspnet-core/framework/localization/LINGYUN.Abp.Localization.CultureMap/README.md +++ b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.CultureMap/README.md @@ -2,52 +2,94 @@ ## 模块说明 -解决存在多种格式的区域性本地化问题 +本模块用于解决存在多种格式的区域性本地化问题。它允许你将不同格式的区域性标识映射到标准格式。 -See: https://github.com/maliming/Owl.Abp.CultureMap +参考项目: [Owl.Abp.CultureMap](https://github.com/maliming/Owl.Abp.CultureMap) -### 基础模块 +## 功能特性 -### 高阶模块 +* 支持将多种格式的区域性标识映射到标准格式 +* 支持区域性（Culture）和UI区域性（UICulture）的独立映射 +* 与ABP请求本地化集成 +* 支持自定义区域性映射规则 -### 权限定义 +## 安装 -### 功能定义 +```bash +dotnet add package LINGYUN.Abp.Localization.CultureMap +``` -### 配置定义 +## 基础模块 -### 如何使用 +* Volo.Abp.AspNetCore +## 配置说明 -```csharp +模块提供了以下配置选项： + +* CulturesMaps：区域性映射列表 +* UiCulturesMaps：UI区域性映射列表 + +每个映射项包含： +* TargetCulture：目标区域性标识 +* SourceCultures：源区域性标识列表 + +## 使用方法 - [DependsOn( - typeof(AbpLocalizationCultureMapModule))] - public class YouProjectModule : AbpModule +1. 添加模块依赖： + +```csharp +[DependsOn( + typeof(AbpLocalizationCultureMapModule))] +public class YouProjectModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) { - public override void ConfigureServices(ServiceConfigurationContext context) + Configure(options => { - Configure(options => + var zhHansCultureMapInfo = new CultureMapInfo { - var zhHansCultureMapInfo = new CultureMapInfo - { - TargetCulture = "zh-Hans", - SourceCultures = new string[] { "zh", "zh_CN", "zh-CN" } - }; - - options.CulturesMaps.Add(zhHansCultureMapInfo); - options.UiCulturesMaps.Add(zhHansCultureMapInfo); - }); - } - - public override void OnApplicationInitialization(ApplicationInitializationContext context) - { - var app = context.GetApplicationBuilder(); + TargetCulture = "zh-Hans", + SourceCultures = new string[] { "zh", "zh_CN", "zh-CN" } + }; + + options.CulturesMaps.Add(zhHansCultureMapInfo); + options.UiCulturesMaps.Add(zhHansCultureMapInfo); + }); + } - app.UseMapRequestLocalization(); - } + public override void OnApplicationInitialization(ApplicationInitializationContext context) + { + var app = context.GetApplicationBuilder(); + + app.UseMapRequestLocalization(); } +} +``` + +## 常见用例 + +1. 统一简体中文区域性标识： +```csharp +options.CulturesMaps.Add(new CultureMapInfo +{ + TargetCulture = "zh-Hans", + SourceCultures = new string[] { "zh", "zh_CN", "zh-CN" } +}); +``` +2. 统一繁体中文区域性标识： +```csharp +options.CulturesMaps.Add(new CultureMapInfo +{ + TargetCulture = "zh-Hant", + SourceCultures = new string[] { "zh_TW", "zh-TW", "zh_HK", "zh-HK" } +}); ``` -### 更新日志 +## 更多信息 + +* [English Documentation](./README.EN.md) +* [ABP本地化文档](https://docs.abp.io/zh-Hans/abp/latest/Localization) + +## 更新日志 diff --git a/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Persistence/README.EN.md b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Persistence/README.EN.md new file mode 100644 index 000000000..283966395 --- /dev/null +++ b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Persistence/README.EN.md @@ -0,0 +1,129 @@ +# LINGYUN.Abp.Localization.Persistence + +## Module Description + +Localization component persistence module, providing functionality to persist localization resources to storage facilities. This module allows you to save static localization documents to persistent storage for easier management and maintenance. + +## Features + +* Support persisting static localization resources to storage facilities +* Provide read and write interfaces for localization resources +* Support custom persistence storage implementation +* Support asynchronous read and write operations +* Support multi-language culture support +* Support selective persistence of specified resources + +## Installation + +```bash +dotnet add package LINGYUN.Abp.Localization.Persistence +``` + +## Base Modules + +* Volo.Abp.Localization + +## Configuration + +The module provides the following configuration options: + +* SaveStaticLocalizationsToPersistence: Whether to enable localization resource persistence (default: true) +* SaveToPersistenceResources: List of resources to be persisted + +## Usage + +1. Add module dependency: + +```csharp +[DependsOn( + typeof(AbpLocalizationPersistenceModule))] +public class YouProjectModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + // Enable persistence facility + options.SaveStaticLocalizationsToPersistence = true; + + // Specify your localization resource type, static documents under this type will be persisted to storage facilities + options.AddPersistenceResource(); + }); + + // Or use extension method to persist localization resource type + Configure(options => + { + // Same effect as above + options.UsePersistence(); + }); + } +} +``` + +## Extension Interfaces + +### ILocalizationPersistenceReader + +Used to read localization resources from persistent storage: + +```csharp +public interface ILocalizationPersistenceReader +{ + // Get localized string for specified resource + LocalizedString GetOrNull(string resourceName, string cultureName, string name); + + // Fill localization dictionary + void Fill(string resourceName, string cultureName, Dictionary dictionary); + + // Asynchronously fill localization dictionary + Task FillAsync(string resourceName, string cultureName, Dictionary dictionary); + + // Get supported cultures list + Task> GetSupportedCulturesAsync(); +} +``` + +### ILocalizationPersistenceWriter + +Used to write localization resources to persistent storage: + +```csharp +public interface ILocalizationPersistenceWriter +{ + // Write language information + Task WriteLanguageAsync(LanguageInfo language); + + // Write resource information + Task WriteResourceAsync(LocalizationResourceBase resource); + + // Get existing texts + Task> GetExistsTextsAsync( + string resourceName, + string cultureName, + IEnumerable keys); + + // Write localization texts + Task WriteTextsAsync(IEnumerable texts); +} +``` + +## Custom Persistence Implementation + +To implement custom persistence storage, you need to: + +1. Implement `ILocalizationPersistenceReader` interface +2. Implement `ILocalizationPersistenceWriter` interface +3. Register your implementation in the module: + +```csharp +public override void ConfigureServices(ServiceConfigurationContext context) +{ + context.Services.AddTransient(); + context.Services.AddTransient(); +} +``` + +## More Information + +* [中文文档](./README.md) +* [ABP Localization Documentation](https://docs.abp.io/en/abp/latest/Localization) diff --git a/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Persistence/README.md b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Persistence/README.md index 10508a7a3..f6a30128b 100644 --- a/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Persistence/README.md +++ b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Persistence/README.md @@ -2,47 +2,128 @@ ## 模块说明 -本地化组件持久层模块, 引用模块可将需要的本地化文档持久化到存储设施 +本地化组件持久层模块，提供将本地化资源持久化到存储设施的功能。此模块允许你将静态本地化文档保存到持久化存储中，方便管理和维护。 -### 基础模块 +## 功能特性 -### 高阶模块 +* 支持将静态本地化资源持久化到存储设施 +* 提供本地化资源的读写接口 +* 支持自定义持久化存储实现 +* 支持异步读写操作 +* 支持多语言文化支持 +* 支持选择性持久化指定的资源 -### 权限定义 +## 安装 -### 功能定义 +```bash +dotnet add package LINGYUN.Abp.Localization.Persistence +``` -### 配置定义 +## 基础模块 -### 如何使用 +* Volo.Abp.Localization +## 配置说明 -```csharp +模块提供以下配置选项： + +* SaveStaticLocalizationsToPersistence：是否启用本地化资源持久化（默认：true） +* SaveToPersistenceResources：需要持久化的资源列表 + +## 使用方法 - [DependsOn( - typeof(AbpLocalizationPersistenceModule))] - public class YouProjectModule : AbpModule +1. 添加模块依赖： + +```csharp +[DependsOn( + typeof(AbpLocalizationPersistenceModule))] +public class YouProjectModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) { - public override void ConfigureServices(ServiceConfigurationContext context) + Configure(options => + { + // 启用持久化设施 + options.SaveStaticLocalizationsToPersistence = true; + + // 指定你的本地化资源类型, 此类型下定义的静态文档将被持久化到存储设施 + options.AddPersistenceResource(); + }); + + // 或者使用扩展方法持久化本地化资源类型 + Configure(options => { - Configure(options => - { - // 启用持久化设施 - options.SaveStaticLocalizationsToPersistence = true; - - // 指定你的本地化资源类型, 此类型下定义的静态文档将被持久化到存储设施 - options.AddPersistenceResource(); - }); - - // 或者使用扩展方法持久化本地化资源类型 - Configure(options => - { - // 效果如上 - options.UsePersistence(); - }); - } + // 效果如上 + options.UsePersistence(); + }); } +} +``` + +## 扩展接口 + +### ILocalizationPersistenceReader + +用于从持久化存储中读取本地化资源： + +```csharp +public interface ILocalizationPersistenceReader +{ + // 获取指定资源的本地化字符串 + LocalizedString GetOrNull(string resourceName, string cultureName, string name); + + // 填充本地化字典 + void Fill(string resourceName, string cultureName, Dictionary dictionary); + // 异步填充本地化字典 + Task FillAsync(string resourceName, string cultureName, Dictionary dictionary); + + // 获取支持的文化列表 + Task> GetSupportedCulturesAsync(); +} +``` + +### ILocalizationPersistenceWriter + +用于将本地化资源写入持久化存储： + +```csharp +public interface ILocalizationPersistenceWriter +{ + // 写入语言信息 + Task WriteLanguageAsync(LanguageInfo language); + + // 写入资源信息 + Task WriteResourceAsync(LocalizationResourceBase resource); + + // 获取已存在的文本 + Task> GetExistsTextsAsync( + string resourceName, + string cultureName, + IEnumerable keys); + + // 写入本地化文本 + Task WriteTextsAsync(IEnumerable texts); +} +``` + +## 自定义持久化实现 + +要实现自定义的持久化存储，需要： + +1. 实现 `ILocalizationPersistenceReader` 接口 +2. 实现 `ILocalizationPersistenceWriter` 接口 +3. 在模块中注册你的实现： + +```csharp +public override void ConfigureServices(ServiceConfigurationContext context) +{ + context.Services.AddTransient(); + context.Services.AddTransient(); +} ``` -### 更新日志 +## 更多信息 + +* [English Documentation](./README.EN.md) +* [ABP本地化文档](https://docs.abp.io/zh-Hans/abp/latest/Localization) diff --git a/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Xml/README.EN.md b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Xml/README.EN.md new file mode 100644 index 000000000..6ca8da7c0 --- /dev/null +++ b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Xml/README.EN.md @@ -0,0 +1,102 @@ +# LINGYUN.Abp.Localization.Xml + +## Module Description + +XML document integration module for localization components, providing XML file-based localization resource support. It includes built-in implementations for both PhysicalFileProvider and VirtualFileProvider. + +## Features + +* Support reading localization resources from XML files +* Support XML files in virtual file system +* Support XML files in physical file system +* Support XML file serialization and deserialization +* Support UTF-8 encoded XML files + +## Installation + +```bash +dotnet add package LINGYUN.Abp.Localization.Xml +``` + +## Base Modules + +* Volo.Abp.Localization + +## Usage + +1. Add module dependency: + +```csharp +[DependsOn( + typeof(AbpLocalizationXmlModule))] +public class YouProjectModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + options.FileSets.AddEmbedded(); + }); + + Configure(options => + { + options.Resources + .Add("en") + // Virtual file system directory in current project + // See: https://docs.abp.io/en/abp/latest/Virtual-File-System + .AddVirtualXml("/LINGYUN/Abp/Localization/Xml/Resources") + // Usually configured in the host project, write the absolute path where XML files are stored + // See: https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.fileproviders.physicalfileprovider + .AddPhysicalXml(Path.Combine(Directory.GetCurrentDirectory(), "Resources")); + }); + } +} +``` + +## XML File Format + +This module uses the [XmlLocalizationFile](./LINGYUN/Abp/Localization/Xml/XmlLocalizationFile.cs) type for XML file serialization and deserialization. + +Example XML file format: + +```xml + + + + + Welcome + Hello, World! + This field is required + + +``` + +## Extension Methods + +The module provides two extension methods for adding XML localization resources: + +1. AddVirtualXml: Add XML files from virtual file system +```csharp +localizationResource.AddVirtualXml("/YourVirtualPath/Localization"); +``` + +2. AddPhysicalXml: Add XML files from physical file system +```csharp +localizationResource.AddPhysicalXml("C:/YourPath/Localization"); +``` + +## Best Practices + +1. Recommended usage for virtual files: + * Embed XML files into the assembly + * Suitable for default localization resources that don't need dynamic modification + +2. Recommended usage for physical files: + * Store in a specific directory in the host project + * Suitable for localization resources that need dynamic modification or are managed by external systems + +## More Information + +* [中文文档](./README.md) +* [ABP Localization Documentation](https://docs.abp.io/en/abp/latest/Localization) +* [ABP Virtual File System](https://docs.abp.io/en/abp/latest/Virtual-File-System) diff --git a/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Xml/README.md b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Xml/README.md index 91f82e12d..40a0e819f 100644 --- a/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Xml/README.md +++ b/aspnet-core/framework/localization/LINGYUN.Abp.Localization.Xml/README.md @@ -2,63 +2,101 @@ ## 模块说明 -本地化组件的Xml文档集成，内置PhysicalFileProvider与VirtualFileProvider实现 +本地化组件的XML文档集成模块，提供基于XML文件的本地化资源支持。内置了物理文件提供程序（PhysicalFileProvider）和虚拟文件提供程序（VirtualFileProvider）的实现。 -### 基础模块 +## 功能特性 -### 高阶模块 +* 支持从XML文件读取本地化资源 +* 支持虚拟文件系统中的XML文件 +* 支持物理文件系统中的XML文件 +* 支持XML文件的序列化和反序列化 +* 支持UTF-8编码的XML文件 -### 权限定义 +## 安装 -### 功能定义 +```bash +dotnet add package LINGYUN.Abp.Localization.Xml +``` -### 配置定义 +## 基础模块 -### 如何使用 +* Volo.Abp.Localization +## 使用方法 -```csharp +1. 添加模块依赖： - [DependsOn( - typeof(AbpLocalizationXmlModule))] - public class YouProjectModule : AbpModule +```csharp +[DependsOn( + typeof(AbpLocalizationXmlModule))] +public class YouProjectModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) { - public override void ConfigureServices(ServiceConfigurationContext context) + Configure(options => { - Configure(options => - { - options.FileSets.AddEmbedded(); - }); - - Configure(options => - { - options.Resources - .Add("en") - // 当前项目中的虚拟文件系统目录,详情见: https://docs.abp.io/en/abp/latest/Virtual-File-System - .AddVirtualXml("/LINGYUN/Abp/Localization/Xml/Resources") - // 一般配置在宿主项目中, 写入宿主项目中存储xml文件的绝对路径(受PhysicalFileProvider的限制) - // 详情见: https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.fileproviders.physicalfileprovider?view=dotnet-plat-ext-5.0 - .AddPhysicalXml(Path.Combine(Directory.GetCurrentDirectory(), "Resources")); - }); - } - } + options.FileSets.AddEmbedded(); + }); + Configure(options => + { + options.Resources + .Add("en") + // 当前项目中的虚拟文件系统目录 + // 详情见: https://docs.abp.io/zh-Hans/abp/latest/Virtual-File-System + .AddVirtualXml("/LINGYUN/Abp/Localization/Xml/Resources") + // 一般配置在宿主项目中, 写入宿主项目中存储xml文件的绝对路径 + // 详情见: https://docs.microsoft.com/zh-cn/dotnet/api/microsoft.extensions.fileproviders.physicalfileprovider + .AddPhysicalXml(Path.Combine(Directory.GetCurrentDirectory(), "Resources")); + }); + } +} ``` -Xml文件格式如下 -序列化: [XmlLocalizationFile](./LINGYUN/Abp/Localization/Xml/XmlLocalizationFile.cs) 类型实现 +## XML文件格式 -```xml +本模块使用 [XmlLocalizationFile](./LINGYUN/Abp/Localization/Xml/XmlLocalizationFile.cs) 类型来序列化和反序列化XML文件。 + +示例XML文件格式： +```xml - - - - - - + + + + 欢迎 + 你好，世界！ + 这是必填字段 + +``` +## 扩展方法 + +模块提供了两个扩展方法来添加XML本地化资源： + +1. AddVirtualXml：添加虚拟文件系统中的XML文件 +```csharp +localizationResource.AddVirtualXml("/YourVirtualPath/Localization"); +``` + +2. AddPhysicalXml：添加物理文件系统中的XML文件 +```csharp +localizationResource.AddPhysicalXml("C:/YourPath/Localization"); ``` -### 更新日志 +## 最佳实践 + +1. 虚拟文件推荐用法： + * 将XML文件嵌入到程序集中 + * 适用于默认的、不需要动态修改的本地化资源 + +2. 物理文件推荐用法： + * 存放在宿主项目的特定目录中 + * 适用于需要动态修改或由外部系统管理的本地化资源 + +## 更多信息 + +* [English Documentation](./README.EN.md) +* [ABP本地化文档](https://docs.abp.io/zh-Hans/abp/latest/Localization) +* [ABP虚拟文件系统](https://docs.abp.io/zh-Hans/abp/latest/Virtual-File-System)