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
     /// <summary>
     /// 初始化本地化字符串
     /// </summary>
-    /// <param name="manager">本地化管理器</param>
-    /// <param name="table">表名</param>
-    /// <param name="key">键名</param>
+    /// <param name="manager">本地化管理器实例</param>
+    /// <param name="table">本地化表名，用于定位本地化资源表</param>
+    /// <param name="key">本地化键名，用于在表中定位具体的本地化文本</param>
+    /// <exception cref="ArgumentNullException">当 manager、table 或 key 为 null 时抛出</exception>
     public LocalizationString(ILocalizationManager manager, string table, string key)
     {
         _manager = manager ?? throw new ArgumentNullException(nameof(manager));
@@ -43,7 +44,13 @@ public class LocalizationString : ILocalizationString
     /// <inheritdoc/>
     public string Key { get; }
 
-    /// <inheritdoc/>
+    /// <summary>
+    /// 添加单个变量到本地化字符串中
+    /// </summary>
+    /// <param name="name">变量名称，用于在模板中匹配对应的占位符</param>
+    /// <param name="value">变量值，将被转换为字符串并替换到对应位置</param>
+    /// <returns>返回当前的 LocalizationString 实例，支持链式调用</returns>
+    /// <exception cref="ArgumentNullException">当 name 为 null 时抛出</exception>
     public ILocalizationString WithVariable(string name, object value)
     {
         if (name == null)
@@ -55,7 +62,12 @@ public class LocalizationString : ILocalizationString
         return this;
     }
 
-    /// <inheritdoc/>
+    /// <summary>
+    /// 批量添加多个变量到本地化字符串中
+    /// </summary>
+    /// <param name="variables">变量元组数组，每个元组包含变量名称和对应的值</param>
+    /// <returns>返回当前的 LocalizationString 实例，支持链式调用</returns>
+    /// <exception cref="ArgumentNullException">当 variables 为 null 时抛出</exception>
     public ILocalizationString WithVariables(params (string name, object value)[] variables)
     {
         if (variables == null)
@@ -71,14 +83,25 @@ public class LocalizationString : ILocalizationString
         return this;
     }
 
-    /// <inheritdoc/>
+    /// <summary>
+    /// 格式化本地化字符串，将模板中的变量占位符替换为实际值
+    /// </summary>
+    /// <returns>格式化后的完整字符串。如果本地化文本不存在，则返回 "[Table.Key]" 格式的占位符</returns>
+    /// <remarks>
+    /// 支持两种格式：
+    /// 1. {variableName} - 简单变量替换
+    /// 2. {variableName:formatter:args} - 使用格式化器进行格式化
+    /// </remarks>
     public string Format()
     {
         var rawText = GetRaw();
         return FormatString(rawText, _variables, _manager);
     }
 
-    /// <inheritdoc/>
+    /// <summary>
+    /// 获取原始的本地化文本，不进行任何变量替换
+    /// </summary>
+    /// <returns>本地化文本。如果在本地化管理器中未找到对应的文本，则返回 "[Table.Key]" 格式的占位符</returns>
     public string GetRaw()
     {
         if (!_manager.TryGetText(Table, Key, out var text))
@@ -89,7 +112,10 @@ public class LocalizationString : ILocalizationString
         return text;
     }
 
-    /// <inheritdoc/>
+    /// <summary>
+    /// 检查当前本地化键是否存在于本地化管理器中
+    /// </summary>
+    /// <returns>如果存在返回 true；否则返回 false</returns>
     public bool Exists()
     {
         return _manager.TryGetText(Table, Key, out _);
@@ -98,6 +124,10 @@ public class LocalizationString : ILocalizationString
     /// <summary>
     /// 格式化字符串（支持变量替换和格式化器）
     /// </summary>
+    /// <param name="template">包含占位符的模板字符串</param>
+    /// <param name="variables">包含变量名称和值的字典</param>
+    /// <param name="manager">本地化管理器实例，用于获取格式化器</param>
+    /// <returns>格式化后的字符串。如果模板为空或 null，则直接返回原模板</returns>
     private static string FormatString(
         string template,
         Dictionary<string, object> variables,
@@ -112,6 +142,13 @@ public class LocalizationString : ILocalizationString
         return FormatVariableRegex.Replace(template, match => FormatMatch(match, variables, manager));
     }
 
+    /// <summary>
+    /// 处理单个正则表达式匹配项，根据是否有格式化器决定如何处理变量值
+    /// </summary>
+    /// <param name="match">正则表达式匹配结果</param>
+    /// <param name="variables">变量字典</param>
+    /// <param name="manager">本地化管理器实例</param>
+    /// <returns>替换后的字符串。如果变量不存在则返回原始匹配值；如果有格式化器则尝试格式化，失败则使用默认格式化</returns>
     private static string FormatMatch(
         Match match,
         Dictionary<string, object> variables,
@@ -134,6 +171,15 @@ public class LocalizationString : ILocalizationString
             : FormatValue(value, manager);
     }
 
+    /// <summary>
+    /// 尝试使用指定的格式化器格式化变量值
+    /// </summary>
+    /// <param name="match">正则表达式匹配结果，用于获取格式化参数</param>
+    /// <param name="value">要格式化的变量值</param>
+    /// <param name="formatterName">格式化器名称</param>
+    /// <param name="manager">本地化管理器实例</param>
+    /// <param name="result">格式化后的结果字符串</param>
+    /// <returns>如果格式化成功返回 true；否则返回 false，此时 result 为空字符串</returns>
     private static bool TryFormatValue(
         Match match,
         object value,
@@ -152,6 +198,12 @@ public class LocalizationString : ILocalizationString
         return false;
     }
 
+    /// <summary>
+    /// 对变量值进行默认格式化，不使用自定义格式化器
+    /// </summary>
+    /// <param name="value">要格式化的值</param>
+    /// <param name="manager">本地化管理器实例，提供当前文化信息</param>
+    /// <returns>格式化后的字符串。如果值实现 IFormattable 接口则使用其 ToString 方法，否则调用默认的 ToString 方法</returns>
     private static string FormatValue(object value, ILocalizationManager manager)
     {
         return value switch
@@ -161,14 +213,23 @@ public class LocalizationString : ILocalizationString
         };
     }
 
+    /// <summary>
+    /// 获取正则表达式匹配组中的可选值
+    /// </summary>
+    /// <param name="match">正则表达式匹配结果</param>
+    /// <param name="groupIndex">要获取的组索引</param>
+    /// <returns>如果该组匹配成功则返回其值；否则返回 null</returns>
     private static string? GetOptionalGroupValue(Match match, int groupIndex)
     {
         return match.Groups[groupIndex].Success ? match.Groups[groupIndex].Value : null;
     }
 
     /// <summary>
-    /// 获取格式化器
+    /// 从本地化管理器获取指定名称的格式化器
     /// </summary>
+    /// <param name="manager">本地化管理器实例</param>
+    /// <param name="name">格式化器名称</param>
+    /// <returns>如果找到对应的格式化器则返回；否则返回 null</returns>
     private static ILocalizationFormatter? GetFormatter(ILocalizationManager manager, string name)
     {
         return manager.GetFormatter(name);