From d588372cffcddd145057b49ba0d14a7b9bca25fc Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Sun, 5 Apr 2026 19:54:09 +0800
Subject: [PATCH] =?UTF-8?q?docs(godot):=20=E6=B7=BB=E5=8A=A0=20Godot=20?=
 =?UTF-8?q?=E8=AE=BE=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

- 新增 Godot 设置模块概述和核心类说明
- 添加音频设置系统详细文档包括 AudioBusMap 和 GodotAudioSettings
- 添加图形设置系统文档包括 GodotGraphicsSettings 实现
- 添加本地化设置系统文档包括 LocalizationMap 和 GodotLocalizationSettings
- 提供完整的架构设计图和使用示例代码
- 添加 API 详细说明和技术实现细节
- 包含最佳实践、性能考虑和故障排除指南
---
 docs/zh-CN/godot/setting.md | 52 ++++++++++++++++++++++++++++++-------
 1 file changed, 42 insertions(+), 10 deletions(-)

diff --git a/docs/zh-CN/godot/setting.md b/docs/zh-CN/godot/setting.md
index 385512ae..5a323626 100644
--- a/docs/zh-CN/godot/setting.md
+++ b/docs/zh-CN/godot/setting.md
@@ -3,7 +3,7 @@
 ## 概述
 
 Godot 设置模块是 GFramework.Godot 的核心组件之一，专门为 Godot 引擎提供游戏设置系统的实现。该模块将通用的设置框架与 Godot
-引擎的特定功能相结合，提供了音频设置和图形设置的完整解决方案。
+引擎的特定功能相结合，提供了音频设置、图形设置和本地化设置的完整解决方案。
 
 ## 核心类
 
@@ -61,23 +61,55 @@ Godot 图形设置实现类，继承自 GraphicsSettings 并实现 IApplyAbleSet
 - 窗口位置自动居中
 - 多显示器支持
 
+### 本地化设置系统
+
+#### LocalizationMap
+
+本地化映射配置类，用于把设置系统中保存的用户可见语言值解析为：
+
+- Godot `TranslationServer` 使用的 locale
+- GFramework `ILocalizationManager` 使用的语言码
+
+默认映射如下：
+
+- `"简体中文"` -> Godot `zh_CN`，框架语言码 `zhs`
+- `"English"` -> Godot `en`，框架语言码 `eng`
+
+未知语言值会稳定回退到英文，避免重启后出现设置值与运行时语言状态不一致。
+
+#### GodotLocalizationSettings
+
+Godot 本地化设置实现类，负责把 `LocalizationSettings` 同时应用到 Godot 引擎与 GFramework 本地化管理器。
+
+**功能：**
+
+- 将语言设置应用到 `TranslationServer.SetLocale(...)`
+- 同步 `ILocalizationManager.SetLanguage(...)`
+- 通过统一映射避免 Godot locale 与框架语言码分裂
+
 ## 架构设计
 
 ```mermaid
 graph TD
     A[AudioSettings] --> B[GodotAudioSettings]
     C[GraphicsSettings] --> D[GodotGraphicsSettings]
-    E[IApplyAbleSettings] --> B
-    E --> D
+    E[LocalizationSettings] --> F[GodotLocalizationSettings]
+    G[IApplyAbleSettings] --> B
+    G --> D
+    G --> F
     
-    G[AudioBusMap] --> B
+    H[AudioBusMap] --> B
+    I[LocalizationMap] --> F
     
-    B --> I[AudioServer API]
-    D --> J[DisplayServer API]
+    B --> J[AudioServer API]
+    D --> K[DisplayServer API]
+    F --> L[TranslationServer API]
+    F --> M[ILocalizationManager]
     
-    K[SettingsSystem] --> L[Apply Method]
-    L --> B
-    L --> D
+    N[SettingsSystem] --> O[Apply Method]
+    O --> B
+    O --> D
+    O --> F
 ```
 
 ## 使用示例
@@ -568,4 +600,4 @@ var windowMode = DisplayServer.WindowGetMode();
 GD.Print($"Screen: {screenSize}");
 GD.Print($"Window: {windowSize} at {windowPos}");
 GD.Print($"Mode: {windowMode}");
-```
\ No newline at end of file
+```