From 5fb96761a305acda0eb4d7d888c5a32f96117b3c Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Wed, 18 Mar 2026 23:25:09 +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=E6=96=87=E6=A1=A3=E5=B9=B6=E5=AE=8C?=
=?UTF-8?q?=E5=96=84=E5=8A=9F=E8=83=BD=E5=AE=9E=E7=8E=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 添加了配置项暂不支持的说明信息
- 扩展了语言变化监听的使用方式，增加命名方法订阅示例
- 完善了覆盖机制的文档说明
- 优化了异常处理逻辑，精确捕获本地化相关异常
- 实现了正则表达式的预编译以提升性能
- 添加了必要的命名空间引用
---
.../Localization/LocalizationManager.cs | 3 +-
.../Localization/LocalizationString.cs | 19 +++++++++----
docs/zh-CN/core/localization.md | 28 ++++++++++++++-----
3 files changed, 37 insertions(+), 13 deletions(-)
diff --git a/GFramework.Core/Localization/LocalizationManager.cs b/GFramework.Core/Localization/LocalizationManager.cs
index 202bbcd..5ff4d88 100644
--- a/GFramework.Core/Localization/LocalizationManager.cs
+++ b/GFramework.Core/Localization/LocalizationManager.cs
@@ -105,8 +105,9 @@ public class LocalizationManager : AbstractSystem, ILocalizationManager
text = GetText(table, key);
return true;
}
- catch
+ catch (LocalizationException)
{
+ // 只捕获本地化相关的异常（键不存在、表不存在等）
text = string.Empty;
return false;
}
diff --git a/GFramework.Core/Localization/LocalizationString.cs b/GFramework.Core/Localization/LocalizationString.cs
index e15a5c1..0beb7b0 100644
--- a/GFramework.Core/Localization/LocalizationString.cs
+++ b/GFramework.Core/Localization/LocalizationString.cs
@@ -8,6 +8,18 @@ namespace GFramework.Core.Localization;
///
public class LocalizationString : ILocalizationString
{
+ ///
+ /// 匹配 {variableName} 或 {variableName:formatter:args} 的正则表达式模式
+ ///
+ private static readonly string FormatVariablePattern =
+ @"\{([a-zA-Z_][a-zA-Z0-9_]*)(?::([a-zA-Z_][a-zA-Z0-9_]*)(?::([^}]+))?)?\}";
+
+ ///
+ /// 预编译的静态正则表达式，用于格式化字符串中的变量替换
+ ///
+ private static readonly Regex FormatVariableRegex =
+ new(FormatVariablePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant);
+
private readonly ILocalizationManager _manager;
private readonly Dictionary _variables;
@@ -96,11 +108,8 @@ public class LocalizationString : ILocalizationString
return template;
}
- // 匹配 {variableName} 或 {variableName:formatter:args}
- var pattern = @"\{([a-zA-Z_][a-zA-Z0-9_]*)(?::([a-zA-Z_][a-zA-Z0-9_]*)(?::([^}]+))?)?\}";
- var regex = new Regex(pattern);
-
- return regex.Replace(template, match =>
+ // 使用预编译的静态正则表达式匹配 {variableName} 或 {variableName:formatter:args}
+ return FormatVariableRegex.Replace(template, match =>
{
var variableName = match.Groups[1].Value;
var formatterName = match.Groups[2].Success ? match.Groups[2].Value : null;
diff --git a/docs/zh-CN/core/localization.md b/docs/zh-CN/core/localization.md
index 440e051..03cb112 100644
--- a/docs/zh-CN/core/localization.md
+++ b/docs/zh-CN/core/localization.md
@@ -103,11 +103,13 @@ bool TryFormat(string format, object value, IFormatProvider? provider, out strin
string DefaultLanguage { get; set; } // 默认语言代码，默认 "eng"
string FallbackLanguage { get; set; } // 回退语言代码，默认 "eng"
string LocalizationPath { get; set; } // 本地化文件路径，默认 "res://localization"
-string OverridePath { get; set; } // 用户覆盖路径，默认 "user://localization_override"
-bool EnableHotReload { get; set; } // 是否启用热重载，默认 true
-bool ValidateOnLoad { get; set; } // 是否在加载时验证，默认 true
+string OverridePath { get; set; } // 用户覆盖路径，默认 "user://localization_override" (暂不支持)
+bool EnableHotReload { get; set; } // 是否启用热重载，默认 true (暂不支持)
+bool ValidateOnLoad { get; set; } // 是否在加载时验证，默认 true (暂不支持)
```
+**注意：** `OverridePath`、`EnableHotReload` 和 `ValidateOnLoad` 配置项已定义但当前版本暂不支持，将在后续版本中实现。
+
## 文件组织
### 目录结构
@@ -247,15 +249,25 @@ foreach (var lang in languages)
### 监听语言变化
```csharp
-// 订阅语言变化事件
+// 方式 1: 使用 lambda 表达式（无法取消订阅）
locManager.SubscribeToLanguageChange(language =>
{
Debug.Log($"Language changed to: {language}");
// 更新 UI、重新加载资源等
});
-// 取消订阅
-locManager.UnsubscribeFromLanguageChange(callback);
+// 方式 2: 使用命名方法（推荐，可以取消订阅）
+void OnLanguageChanged(string language)
+{
+ Debug.Log($"Language changed to: {language}");
+ // 更新 UI、重新加载资源等
+}
+
+// 订阅
+locManager.SubscribeToLanguageChange(OnLanguageChanged);
+
+// 取消订阅（使用相同的方法引用）
+locManager.UnsubscribeFromLanguageChange(OnLanguageChanged);
```
## 高级功能
@@ -278,7 +290,9 @@ var text = locManager.GetText("common", "new.feature");
### 覆盖机制
-用户可以在 `user://localization_override/` 目录下放置覆盖文件：
+**注意：** 覆盖机制功能已规划但当前版本暂不支持，将在后续版本中实现。
+
+未来版本中，用户可以在 `user://localization_override/` 目录下放置覆盖文件：
```json
// user://localization_override/eng/common.json