From b5c67850ce039311fcd6d9130397a9370cfb7cbf Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Thu, 19 Mar 2026 09:20:43 +0800
Subject: [PATCH] =?UTF-8?q?docs(localization):=20=E6=9B=B4=E6=96=B0?=
=?UTF-8?q?=E6=9C=AC=E5=9C=B0=E5=8C=96=E5=AD=97=E7=AC=A6=E4=B8=B2=E7=B1=BB?=
=?UTF-8?q?=E7=9A=84XML=E6=96=87=E6=A1=A3=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 为构造函数添加更详细的参数描述和异常说明
- 为WithVariable方法添加完整的XML文档注释
- 为WithVariables方法添加完整的XML文档注释
- 为Format方法添加详细的返回值和备注信息
- 为GetRaw方法添加完整的XML文档注释
- 为Exists方法添加完整的XML文档注释
- 为私有FormatString方法添加参数和返回值说明
- 为私有FormatMatch方法添加详细的处理逻辑描述
- 为私有TryFormatValue方法添加格式化器相关参数说明
- 为私有FormatValue方法添加默认格式化逻辑说明
- 为私有GetOptionalGroupValue方法添加功能说明
- 为私有GetFormatter方法添加获取格式化器的详细描述
---
.../Localization/LocalizationString.cs | 79 ++++++++++++++++---
1 file changed, 70 insertions(+), 9 deletions(-)
diff --git a/GFramework.Core/Localization/LocalizationString.cs b/GFramework.Core/Localization/LocalizationString.cs
index 48eba3a..15832ab 100644
--- a/GFramework.Core/Localization/LocalizationString.cs
+++ b/GFramework.Core/Localization/LocalizationString.cs
@@ -26,9 +26,10 @@ public class LocalizationString : ILocalizationString
///
/// 初始化本地化字符串
///
- /// 本地化管理器
- /// 表名
- /// 键名
+ /// 本地化管理器实例
+ /// 本地化表名，用于定位本地化资源表
+ /// 本地化键名，用于在表中定位具体的本地化文本
+ /// 当 manager、table 或 key 为 null 时抛出
public LocalizationString(ILocalizationManager manager, string table, string key)
{
_manager = manager ?? throw new ArgumentNullException(nameof(manager));
@@ -43,7 +44,13 @@ public class LocalizationString : ILocalizationString
///
public string Key { get; }
- ///
+ ///
+ /// 添加单个变量到本地化字符串中
+ ///
+ /// 变量名称，用于在模板中匹配对应的占位符
+ /// 变量值，将被转换为字符串并替换到对应位置
+ /// 返回当前的 LocalizationString 实例，支持链式调用
+ /// 当 name 为 null 时抛出
public ILocalizationString WithVariable(string name, object value)
{
if (name == null)
@@ -55,7 +62,12 @@ public class LocalizationString : ILocalizationString
return this;
}
- ///
+ ///
+ /// 批量添加多个变量到本地化字符串中
+ ///
+ /// 变量元组数组，每个元组包含变量名称和对应的值
+ /// 返回当前的 LocalizationString 实例，支持链式调用
+ /// 当 variables 为 null 时抛出
public ILocalizationString WithVariables(params (string name, object value)[] variables)
{
if (variables == null)
@@ -71,14 +83,25 @@ public class LocalizationString : ILocalizationString
return this;
}
- ///
+ ///
+ /// 格式化本地化字符串，将模板中的变量占位符替换为实际值
+ ///
+ /// 格式化后的完整字符串。如果本地化文本不存在，则返回 "[Table.Key]" 格式的占位符
+ ///
+ /// 支持两种格式：
+ /// 1. {variableName} - 简单变量替换
+ /// 2. {variableName:formatter:args} - 使用格式化器进行格式化
+ ///
public string Format()
{
var rawText = GetRaw();
return FormatString(rawText, _variables, _manager);
}
- ///
+ ///
+ /// 获取原始的本地化文本，不进行任何变量替换
+ ///
+ /// 本地化文本。如果在本地化管理器中未找到对应的文本，则返回 "[Table.Key]" 格式的占位符
public string GetRaw()
{
if (!_manager.TryGetText(Table, Key, out var text))
@@ -89,7 +112,10 @@ public class LocalizationString : ILocalizationString
return text;
}
- ///
+ ///
+ /// 检查当前本地化键是否存在于本地化管理器中
+ ///
+ /// 如果存在返回 true；否则返回 false
public bool Exists()
{
return _manager.TryGetText(Table, Key, out _);
@@ -98,6 +124,10 @@ public class LocalizationString : ILocalizationString
///
/// 格式化字符串（支持变量替换和格式化器）
///
+ /// 包含占位符的模板字符串
+ /// 包含变量名称和值的字典
+ /// 本地化管理器实例，用于获取格式化器
+ /// 格式化后的字符串。如果模板为空或 null，则直接返回原模板
private static string FormatString(
string template,
Dictionary variables,
@@ -112,6 +142,13 @@ public class LocalizationString : ILocalizationString
return FormatVariableRegex.Replace(template, match => FormatMatch(match, variables, manager));
}
+ ///
+ /// 处理单个正则表达式匹配项，根据是否有格式化器决定如何处理变量值
+ ///
+ /// 正则表达式匹配结果
+ /// 变量字典
+ /// 本地化管理器实例
+ /// 替换后的字符串。如果变量不存在则返回原始匹配值；如果有格式化器则尝试格式化，失败则使用默认格式化
private static string FormatMatch(
Match match,
Dictionary variables,
@@ -134,6 +171,15 @@ public class LocalizationString : ILocalizationString
: FormatValue(value, manager);
}
+ ///
+ /// 尝试使用指定的格式化器格式化变量值
+ ///
+ /// 正则表达式匹配结果，用于获取格式化参数
+ /// 要格式化的变量值
+ /// 格式化器名称
+ /// 本地化管理器实例
+ /// 格式化后的结果字符串
+ /// 如果格式化成功返回 true；否则返回 false，此时 result 为空字符串
private static bool TryFormatValue(
Match match,
object value,
@@ -152,6 +198,12 @@ public class LocalizationString : ILocalizationString
return false;
}
+ ///
+ /// 对变量值进行默认格式化，不使用自定义格式化器
+ ///
+ /// 要格式化的值
+ /// 本地化管理器实例，提供当前文化信息
+ /// 格式化后的字符串。如果值实现 IFormattable 接口则使用其 ToString 方法，否则调用默认的 ToString 方法
private static string FormatValue(object value, ILocalizationManager manager)
{
return value switch
@@ -161,14 +213,23 @@ public class LocalizationString : ILocalizationString
};
}
+ ///
+ /// 获取正则表达式匹配组中的可选值
+ ///
+ /// 正则表达式匹配结果
+ /// 要获取的组索引
+ /// 如果该组匹配成功则返回其值；否则返回 null
private static string? GetOptionalGroupValue(Match match, int groupIndex)
{
return match.Groups[groupIndex].Success ? match.Groups[groupIndex].Value : null;
}
///
- /// 获取格式化器
+ /// 从本地化管理器获取指定名称的格式化器
///
+ /// 本地化管理器实例
+ /// 格式化器名称
+ /// 如果找到对应的格式化器则返回；否则返回 null
private static ILocalizationFormatter? GetFormatter(ILocalizationManager manager, string name)
{
return manager.GetFormatter(name);