Merge pull request #2 from willysoft/docs/translate-xml-comments

docs: Translate XML comments from Chinese to English

Author: willysoft

src/AutoQuery.AspNetCore/AutoQueryServiceExtensions.cs

@@ -8,16 +8,16 @@
 namespace Microsoft.AspNetCore.Builder;
 
 /// <summary>
-/// 提供查詢服務相關的擴展方法。
+/// Provides extension methods related to query services.
 /// </summary>
 public static class AutoQueryServiceExtensions
 {
     /// <summary>
-    /// 向服務集合中添加查詢建構器服務。
+    /// Adds query builder services to the service collection.
     /// </summary>
-    /// <param name="services">服務集合。</param>
-    /// <param name="assembly">要應用配置的程序集。</param>
-    /// <returns>更新後的服務集合。</returns>
+    /// <param name="services">The service collection.</param>
+    /// <param name="assembly">The assembly to apply configurations from.</param>
+    /// <returns>The updated service collection.</returns>
     public static IServiceCollection AddAutoQuery(this IServiceCollection services, Assembly assembly)
     {
         ArgumentNullException.ThrowIfNull(services);

src/AutoQuery.AspNetCore/EnableFieldProjectionAttribute.cs

@@ -13,7 +13,7 @@
 namespace AutoQuery.AspNetCore;
 
 /// <summary>
-/// 字段投影屬性，用於在返回結果中僅包含指定的字段。
+/// Field projection attribute used to include only specified fields in the returned result.
 /// </summary>
 public class EnableFieldProjectionAttribute : ActionFilterAttribute
 {
@@ -24,18 +24,18 @@ public class EnableFieldProjectionAttribute : ActionFilterAttribute
     private IQueryOptions? _queryOptions;
 
     /// <summary>
-    /// 在操作執行之前調用，從操作參數中提取 QueryOptions。
+    /// Called before the action is executed to extract QueryOptions from the action parameters.
     /// </summary>
-    /// <param name="context">操作執行上下文。</param>
+    /// <param name="context">The action execution context.</param>
     public override void OnActionExecuting(ActionExecutingContext context)
     {
         _queryOptions = ExtractQueryOptions(context);
     }
 
     /// <summary>
-    /// 在操作執行之後調用，根據指定的字段過濾返回結果。
+    /// Called after the action is executed to filter the returned result based on the specified fields.
     /// </summary>
-    /// <param name="context">操作執行上下文。</param>
+    /// <param name="context">The action execution context.</param>
     public override void OnActionExecuted(ActionExecutedContext context)
     {
         if (_queryOptions == null || string.IsNullOrEmpty(_queryOptions.Fields))
@@ -53,12 +53,12 @@ public override void OnActionExecuted(ActionExecutedContext context)
     }
 
     /// <summary>
-    /// 過濾結果，僅包含選擇的字段。
+    /// Filters the result to include only the selected fields.
     /// </summary>
-    /// <param name="value">要過濾的對象。</param>
-    /// <param name="selectedFields">選擇的字段集合。</param>
-    /// <param name="serializerOptions">JSON 序列化選項。</param>
-    /// <returns>過濾後的對象。</returns>
+    /// <param name="value">The object to filter.</param>
+    /// <param name="selectedFields">The set of selected fields.</param>
+    /// <param name="serializerOptions">JSON serialization options.</param>
+    /// <returns>The filtered object.</returns>
     private static object FilterResult(object value, HashSet<string> selectedFields, JsonSerializerOptions serializerOptions)
     {
         if (value is IEnumerable<object> enumerable)
@@ -76,12 +76,12 @@ private static object FilterResult(object value, HashSet<string> selectedFields,
     }
 
     /// <summary>
-    /// 過濾集合類型的結果。
+    /// Filters a collection-type result.
     /// </summary>
-    /// <param name="enumerable">要過濾的集合。</param>
-    /// <param name="selectedFields">選擇的字段集合。</param>
-    /// <param name="serializerOptions">JSON 序列化選項。</param>
-    /// <returns>過濾後的集合。</returns>
+    /// <param name="enumerable">The collection to filter.</param>
+    /// <param name="selectedFields">The set of selected fields.</param>
+    /// <param name="serializerOptions">JSON serialization options.</param>
+    /// <returns>The filtered collection.</returns>
     private static List<Dictionary<string, object?>> FilterEnumerable(IEnumerable<object> enumerable, HashSet<string> selectedFields, JsonSerializerOptions serializerOptions)
     {
         var result = new List<Dictionary<string, object?>>();
@@ -94,13 +94,13 @@ private static object FilterResult(object value, HashSet<string> selectedFields,
     }
 
     /// <summary>
-    /// 過濾單個物件的結果。
+    /// Filters the result of a single object.
     /// </summary>
-    /// <param name="value">要過濾的物件。</param>
-    /// <param name="selectedFields">選擇的字段集合。</param>
-    /// <param name="serializerOptions">JSON 序列化選項。</param>
-    /// <param name="firstLevelOnly">是否僅過濾第一層屬性。</param>
-    /// <returns>過濾後的字典。</returns>
+    /// <param name="value">The object to filter.</param>
+    /// <param name="selectedFields">The set of selected fields.</param>
+    /// <param name="serializerOptions">JSON serialization options.</param>
+    /// <param name="firstLevelOnly">Whether to filter only the first-level properties.</param>
+    /// <returns>The filtered dictionary.</returns>
     private static Dictionary<string, object?> FilterObject(object value, HashSet<string> selectedFields, JsonSerializerOptions serializerOptions, bool firstLevelOnly = false)
     {
         var result = new Dictionary<string, object?>();
@@ -138,20 +138,20 @@ private static object FilterResult(object value, HashSet<string> selectedFields,
     }
 
     /// <summary>
-    /// 從操作上下文中提取 QueryOptions。
+    /// Extracts QueryOptions from the action context.
     /// </summary>
-    /// <param name="context">操作執行上下文。</param>
-    /// <returns>提取的 QueryOptions。</returns>
+    /// <param name="context">The action execution context.</param>
+    /// <returns>The extracted QueryOptions.</returns>
     private static IQueryOptions? ExtractQueryOptions(ActionExecutingContext context)
     {
         return context.ActionArguments.Values.OfType<IQueryOptions>().FirstOrDefault();
     }
 
     /// <summary>
-    /// 解析選擇的字段。
+    /// Parses the selected fields.
     /// </summary>
-    /// <param name="fields">逗號分隔的字段名稱。</param>
-    /// <returns>選擇的字段集合。</returns>
+    /// <param name="fields">Comma-separated field names.</param>
+    /// <returns>The set of selected fields.</returns>
     private static HashSet<string> ParseSelectedFields(string fields)
     {
         return fields.Split(',')
@@ -160,21 +160,21 @@ private static HashSet<string> ParseSelectedFields(string fields)
     }
 
     /// <summary>
-    /// 獲取 JSON 序列化選項。
+    /// Gets the JSON serialization options.
     /// </summary>
-    /// <param name="context">操作執行上下文。</param>
-    /// <returns>JSON 序列化選項。</returns>
+    /// <param name="context">The action execution context.</param>
+    /// <returns>The JSON serialization options.</returns>
     private static JsonSerializerOptions GetSerializerOptions(ActionExecutedContext context)
     {
         return context.HttpContext.RequestServices.GetRequiredService<IOptions<JsonOptions>>().Value.JsonSerializerOptions;
     }
 
     /// <summary>
-    /// 使用表達樹取得屬性的值。
+    /// Gets the value of a property using expression trees.
     /// </summary>
-    /// <param name="property">屬性信息。</param>
-    /// <param name="instance">對象實例。</param>
-    /// <returns>屬性的值。</returns>
+    /// <param name="property">The property information.</param>
+    /// <param name="instance">The object instance.</param>
+    /// <returns>The value of the property.</returns>
     private static object? GetPropertyValue(PropertyInfo property, object instance)
     {
         if (!_propertyAccessorsCache.TryGetValue(property, out var accessor))
@@ -191,11 +191,11 @@ private static JsonSerializerOptions GetSerializerOptions(ActionExecutedContext
     }
 
     /// <summary>
-    /// 獲取屬性的 JSON 屬性名稱。
+    /// Gets the JSON property name of a property.
     /// </summary>
-    /// <param name="propInfo">屬性信息。</param>
-    /// <param name="serializerOptions">JSON 序列化選項。</param>
-    /// <returns>屬性的 JSON 名稱。</returns>
+    /// <param name="propInfo">The property information.</param>
+    /// <param name="serializerOptions">JSON serialization options.</param>
+    /// <returns>The JSON name of the property.</returns>
     private static string GetJsonPropertyName(PropertyInfo propInfo, JsonSerializerOptions serializerOptions)
     {
         var jsonPropertyNameAttr = _jsonPropertyNameCache[propInfo];
@@ -205,9 +205,9 @@ private static string GetJsonPropertyName(PropertyInfo propInfo, JsonSerializerO
     }
 
     /// <summary>
-    /// 緩存類型的屬性信息。
+    /// Caches the property information of a type.
     /// </summary>
-    /// <param name="type">要緩存的類型。</param>
+    /// <param name="type">The type to cache.</param>
     private static void CacheProperties(Type type)
     {
         if (!_propertyInfoCache.ContainsKey(type))
@@ -224,10 +224,10 @@ private static void CacheProperties(Type type)
     }
 
     /// <summary>
-    /// 確定狀態碼是否表示成功。
+    /// Determines whether the status code indicates success.
     /// </summary>
-    /// <param name="statusCode">HTTP 狀態碼。</param>
-    /// <returns>如果狀態碼表示成功，則為 true；否則為 false。</returns>
+    /// <param name="statusCode">The HTTP status code.</param>
+    /// <returns>True if the status code indicates success; otherwise, false.</returns>
     private static bool IsSuccessStatusCode(int statusCode)
     {
         return statusCode >= 200 && statusCode < 300;

src/AutoQuery/Abstractions/IFilterExpressionBuilder.cs

@@ -3,16 +3,16 @@
 namespace AutoQuery.Abstractions;
 
 /// <summary>
-/// 定義篩選查詢屬性建構器的介面。
+/// Defines the interface for a filter query property builder.
 /// </summary>
-/// <typeparam name="TData">數據的類型。</typeparam>
-/// <typeparam name="TQueryProperty">查詢屬性的類型。</typeparam>
+/// <typeparam name="TData">The type of the data.</typeparam>
+/// <typeparam name="TQueryProperty">The type of the query property.</typeparam>
 public interface IFilterExpressionBuilder<TData, TQueryProperty>
 {
     /// <summary>
-    /// 構建篩選表達式。
+    /// Builds the filter expression.
     /// </summary>
-    /// <param name="filterValue">篩選屬性的值。</param>
-    /// <returns>篩選表達式。</returns>
+    /// <param name="filterValue">The value of the filter property.</param>
+    /// <returns>The filter expression.</returns>
     Expression<Func<TData, bool>> BuildFilterExpression(TQueryProperty filterValue);
 }

src/AutoQuery/Abstractions/IFilterQueryConfiguration.cs

@@ -1,15 +1,15 @@
 namespace AutoQuery.Abstractions;
 
 /// <summary>
-/// 定義篩選查詢配置的介面。
+/// Defines the interface for filter query configuration.
 /// </summary>
-/// <typeparam name="TQueryOptions">查詢選項的類型。</typeparam>
-/// <typeparam name="TData">數據的類型。</typeparam>
+/// <typeparam name="TQueryOptions">The type of the query options.</typeparam>
+/// <typeparam name="TData">The type of the data.</typeparam>
 public interface IFilterQueryConfiguration<TQueryOptions, TData>
 {
     /// <summary>
-    /// 配置篩選查詢建構器。
+    /// Configures the filter query builder.
     /// </summary>
-    /// <param name="builder">篩選查詢建構器。</param>
+    /// <param name="builder">The filter query builder.</param>
     void Configure(FilterQueryBuilder<TQueryOptions, TData> builder);
 }

src/AutoQuery/Abstractions/IQueryOptions.cs

@@ -1,17 +1,17 @@
 namespace AutoQuery.Abstractions;
 
 /// <summary>
-/// 查詢參數
+/// Query parameters.
 /// </summary>
 public interface IQueryOptions
 {
     /// <summary>
-    /// 選擇的欄位
+    /// Selected fields.
     /// </summary>
     string? Fields { get; set; }
 
     /// <summary>
-    /// 排序欄位 
+    /// Sorting fields.
     /// </summary>
     string? Sort { get; set; }
 }

src/AutoQuery/Abstractions/IQueryPagedOptions.cs

@@ -1,17 +1,17 @@
 namespace AutoQuery.Abstractions;
 
 /// <summary>
-/// 查詢已分頁參數
+/// Query parameters for paginated results.
 /// </summary>
 public interface IQueryPagedOptions : IQueryOptions
 {
     /// <summary>
-    /// 當前頁數
+    /// Current page number.
     /// </summary>
     int? Page { get; set; }
 
     /// <summary>
-    /// 每頁資料數量
+    /// Number of items per page.
     /// </summary>
     int? PageSize { get; set; }
 }

src/AutoQuery/Abstractions/IQueryProcessor.cs

@@ -3,27 +3,27 @@
 namespace AutoQuery.Abstractions;
 
 /// <summary>
-/// 定義查詢建構器服務的介面。
+/// Defines the interface for query builder services.
 /// </summary>
 public interface IQueryProcessor
 {
     /// <summary>
-    /// 構建篩選表達式。
+    /// Builds the filter expression.
     /// </summary>
-    /// <typeparam name="TData">數據的類型。</typeparam>
-    /// <typeparam name="TQueryOptions">查詢選項的類型。</typeparam>
-    /// <param name="queryOptions">查詢選項。</param>
-    /// <returns>篩選表達式，如果沒有篩選條件則為 null。</returns>
+    /// <typeparam name="TData">The type of the data.</typeparam>
+    /// <typeparam name="TQueryOptions">The type of the query options.</typeparam>
+    /// <param name="queryOptions">The query options.</param>
+    /// <returns>The filter expression, or null if no filter conditions exist.</returns>
     Expression<Func<TData, bool>>? BuildFilterExpression<TData, TQueryOptions>(TQueryOptions queryOptions)
         where TQueryOptions : IQueryOptions;
 
     /// <summary>
-    /// 構建選擇器表達式。
+    /// Builds the selector expression.
     /// </summary>
-    /// <typeparam name="TData">數據的類型。</typeparam>
-    /// <typeparam name="TQueryOptions">查詢選項的類型。</typeparam>
-    /// <param name="queryOptions">查詢選項。</param>
-    /// <returns>選擇器表達式，如果沒有選擇條件則為 null。</returns>
+    /// <typeparam name="TData">The type of the data.</typeparam>
+    /// <typeparam name="TQueryOptions">The type of the query options.</typeparam>
+    /// <param name="queryOptions">The query options.</param>
+    /// <returns>The selector expression, or null if no selection conditions exist.</returns>
     Expression<Func<TData, TData>>? BuildSelectorExpression<TData, TQueryOptions>(TQueryOptions queryOptions)
         where TQueryOptions : IQueryOptions;
 }

src/AutoQuery/ComplexFilterQueryPropertyBuilder.cs

@@ -5,30 +5,30 @@
 namespace AutoQuery;
 
 /// <summary>
-/// 用於構建篩選查詢屬性的建構器類別。
+/// A builder class for constructing filter query properties.
 /// </summary>
-/// <typeparam name="TData">數據的類型。</typeparam>
-/// <typeparam name="TQueryProperty">查詢屬性的類型。</typeparam>
-/// <typeparam name="TDataProperty">數據屬性的類型。</typeparam>
+/// <typeparam name="TData">The type of the data.</typeparam>
+/// <typeparam name="TQueryProperty">The type of the query property.</typeparam>
+/// <typeparam name="TDataProperty">The type of the data property.</typeparam>
 public class ComplexFilterQueryPropertyBuilder<TData, TQueryProperty, TDataProperty> : IFilterExpressionBuilder<TData, TQueryProperty>
 {
     private Expression<Func<TData, TDataProperty>> _filterKeySelector;
     private List<(Expression<Func<TQueryProperty, TDataProperty, bool>> Expression, LogicalOperator Logical)> _filterExpressions = new();
 
     /// <summary>
-    /// 初始化 <see cref="ComplexFilterQueryPropertyBuilder{TData, TQueryProperty, TDataProperty}"/> 類別的新實例。
+    /// Initializes a new instance of the <see cref="ComplexFilterQueryPropertyBuilder{TData, TQueryProperty, TDataProperty}"/> class.
     /// </summary>
-    /// <param name="filterKeySelector">數據中的篩選鍵選擇器。</param>
+    /// <param name="filterKeySelector">The filter key selector in the data.</param>
     public ComplexFilterQueryPropertyBuilder(Expression<Func<TData, TDataProperty>> filterKeySelector)
     {
         _filterKeySelector = filterKeySelector;
     }
 
     /// <summary>
-    /// 添加篩選表達式。
+    /// Adds a filter expression.
     /// </summary>
-    /// <param name="filterExpression">篩選表達式。</param>
-    /// <param name="logicalOperator">邏輯運算符。</param>
+    /// <param name="filterExpression">The filter expression.</param>
+    /// <param name="logicalOperator">The logical operator.</param>
     public void AddFilterExpression(Expression<Func<TQueryProperty, TDataProperty, bool>> filterExpression, LogicalOperator logicalOperator)
     {
         _filterExpressions.Add((filterExpression, logicalOperator));
@@ -56,4 +56,4 @@ public Expression<Func<TData, bool>> BuildFilterExpression(TQueryProperty filter
 
         return Expression.Lambda<Func<TData, bool>>(finalExpression ?? Expression.Constant(true), parameter);
     }
-}
+}