如何为Godot插件添加多语言支持？

<think>为了为Godot插件添加多语言支持，我们需要确保插件中的字符串可以通过翻译系统进行本地化。以下是详细步骤： ### 步骤1: 准备翻译文件 在插件目录中创建`translations`文件夹，并添加对应的`.po`文件（例如`plugin_zh_CN.po`）。文件内容格式如下： ```po msgid "" msgstr "" "Project-Id-Version: My Plugin\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" msgid "PLUGIN_HELLO" msgstr "你好，世界！" ``` ### 步骤2: 在插件代码中使用翻译 在插件的GDScript代码中，使用`tr()`函数包裹所有需要翻译的字符串： ```gdscript func show_message(): # 错误：直接使用字符串 # print("Hello, World!") # 正确：使用tr函数 print(tr("PLUGIN_HELLO")) ``` ### 步骤3: 注册插件翻译 在插件的入口脚本（通常是`plugin.gd`）中，当插件启用时加载翻译文件： ```gdscript # plugin.gd var _translation: Translation func _enter_tree(): # 加载翻译文件 _translation = load("res://addons/your_plugin/translations/plugin_zh_CN.po") TranslationServer.add_translation(_translation) func _exit_tree(): # 卸载翻译文件 TranslationServer.remove_translation(_translation) ``` ### 步骤4: 处理编辑器翻译（可选） 如果插件有编辑器界面，需要额外处理编辑器的翻译。Godot编辑器有自己的翻译系统，可以通过以下方式添加： ```gdscript # 在plugin.gd中 func _enter_tree(): # ... 同上 # 如果是编辑器插件，还需要设置编辑器语言 if Engine.is_editor_hint(): # 重新加载编辑器界面（需要自定义方法） update_editor_interface() # 由于Godot编辑器不会实时刷新翻译，需要手动更新界面 func update_editor_interface(): # 遍历所有编辑器界面控件并更新文本 # 注意：这需要你自行管理插件的编辑器界面节点 pass ``` ### 步骤5: 提供语言切换支持 如果插件需要运行时切换语言，可以添加： ```gdscript func set_plugin_language(locale: String): TranslationServer.set_locale(locale) # 更新插件界面（需要自行实现） update_plugin_interface() ``` ### 完整示例代码 以下是一个插件多语言支持的完整示例： ```gdscript # plugin.gd @tool extends EditorPlugin var _translation: Translation func _enter_tree(): # 加载翻译文件 _translation = load("res://addons/my_plugin/translations/plugin_zh_CN.po") TranslationServer.add_translation(_translation) # 如果是编辑器插件，设置编辑器语言（可选） if Engine.is_editor_hint(): # 假设我们希望插件使用项目设置的语言 var locale = ProjectSettings.get_setting("application/locale/language") TranslationServer.set_locale(locale) # 初始化界面 add_my_control() func _exit_tree(): TranslationServer.remove_translation(_translation) remove_my_control() # 添加自定义控件（示例） func add_my_control(): var button = Button.new() button.text = tr("PLUGIN_BUTTON_TEXT") add_control_to_container(EditorPlugin.CONTAINER_TOOLBAR, button) func remove_my_control(): # 移除控件的逻辑 pass ``` ### 注意事项： 1. **唯一键名**：确保翻译键在整个项目中唯一（建议加上插件前缀） 2. **热重载**：编辑器插件在语言切换后需要手动刷新界面 3. **测试**：在项目设置中切换语言测试插件文本是否更新 4. **提取字符串**：使用Godot引擎自带的字符串提取工具（需从源码编译）或第三方工具收集所有`tr()`中的字符串 ### 高级技巧： - **动态加载**：根据系统语言自动加载对应翻译文件 - **回退机制**：当翻译缺失时使用默认语言（英文） - **占位符处理**： ```gdscript var message = tr("PLUGIN_WELCOME_MSG").format({ "user": username }) ``` §§相关问题§§: 1. 如何在不重启Godot编辑器的情况下刷新插件翻译？ 2. Godot的翻译系统中，如何处理带变量的字符串（如“欢迎{name}”）？ 3. 如何为Godot插件创建翻译文件（.po）并管理翻译条目？ 4. 在Godot中，如何实现插件语言与主项目语言的隔离？</think># 为 Godot 插件添加多语言支持 为 Godot 插件添加多语言支持需要特殊的处理，因为插件需要独立于主项目管理自己的翻译资源。以下是完整的解决方案： ## 完整实现步骤 ### 1. 创建插件翻译文件结构 在插件目录中创建专门的翻译文件夹： ``` res://addons/your_plugin/ ├── translations/ │ ├── en.po # 英文翻译 │ ├── zh_CN.po # 简体中文翻译 │ └── zh_TW.po # 繁体中文翻译 ├── plugin.gd # 主插件脚本 └── your_plugin.cfg # 插件配置文件 ``` ### 2. 实现插件翻译加载器 在 `plugin.gd` 中添加翻译加载逻辑： ```gdscript # plugin.gd @tool extends EditorPlugin # 存储所有加载的翻译资源 var translations = [] func _enter_tree(): # 加载插件翻译文件 load_translations() # 设置插件界面语言 set_plugin_language() # 加载所有翻译文件 func load_translations(): var translation_dir = "res://addons/your_plugin/translations/" var dir = DirAccess.open(translation_dir) if dir: dir.list_dir_begin() var file_name = dir.get_next() while file_name != "": if file_name.ends_with(".po"): var translation = load(translation_dir + file_name) if translation: TranslationServer.add_translation(translation) translations.append(translation) file_name = dir.get_next() # 设置插件语言 func set_plugin_language(): # 获取编辑器语言设置 var editor_lang = EditorInterface.get_editor_settings().get_setting("interface/editor/editor_language") # 如果没有设置编辑器语言，使用系统语言 if editor_lang == "": editor_lang = OS.get_locale_language() # 设置插件使用的语言 TranslationServer.set_locale(editor_lang) # 清理资源 func _exit_tree(): for translation in translations: TranslationServer.remove_translation(translation) translations.clear() ``` ### 3. 创建翻译文件示例 `en.po` (英文): ```po msgid "" msgstr "" "Project-Id-Version: My Plugin\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" msgid "PLUGIN_NAME" msgstr "My Awesome Plugin" msgid "PLUGIN_BUTTON_TOOLTIP" msgstr "Click to open plugin panel" ``` `zh_CN.po` (简体中文): ```po msgid "" msgstr "" "Project-Id-Version: My Plugin\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" msgid "PLUGIN_NAME" msgstr "我的超棒插件" msgid "PLUGIN_BUTTON_TOOLTIP" msgstr "点击打开插件面板" ``` ### 4. 在插件界面中使用翻译 在插件面板脚本中使用 `tr()` 函数： ```gdscript # plugin_panel.gd @tool extends Control func _ready(): # 设置插件名称 $TitleLabel.text = tr("PLUGIN_NAME") # 设置按钮文本和提示 $ActionButton.text = tr("PLUGIN_BUTTON") $ActionButton.tooltip_text = tr("PLUGIN_BUTTON_TOOLTIP") # 带参数的翻译 var status = tr("PLUGIN_STATUS").format({"status": "active"}) $StatusLabel.text = status ``` ### 5. 处理带参数的翻译 在翻译文件中添加带参数的条目： ```po # en.po msgid "PLUGIN_STATUS" msgstr "Plugin status: {status}" # zh_CN.po msgid "PLUGIN_STATUS" msgstr "插件状态: {status}" ``` 在代码中使用 `format()` 方法替换参数： ```gdscript var status_text = tr("PLUGIN_STATUS").format({"status": "active"}) ``` ### 6. 实现语言切换功能（可选） 如果插件需要运行时切换语言： ```gdscript # plugin_panel.gd # 语言切换下拉菜单 func _on_LanguageOptionButton_item_selected(index): var locale = $LanguageOptionButton.get_item_metadata(index) TranslationServer.set_locale(locale) refresh_ui_texts() # 刷新所有UI文本 func refresh_ui_texts(): $TitleLabel.text = tr("PLUGIN_NAME") $ActionButton.text = tr("PLUGIN_BUTTON") # 更新其他所有文本... ``` ## 关键注意事项 1. **命名空间隔离**： - 使用插件前缀避免与主项目翻译键冲突（如 `MYPLUGIN_BUTTON_OK`） - 建议使用插件名称作为前缀 2. **编辑器插件特殊处理**： - 编辑器插件需要监听编辑器语言设置变化： ```gdscript func _enter_tree(): # 监听编辑器设置变化 EditorInterface.get_editor_settings().settings_changed.connect(_on_settings_changed) func _on_settings_changed(): var new_lang = EditorInterface.get_editor_settings().get_setting("interface/editor/editor_language") if new_lang != current_lang: set_plugin_language(new_lang) refresh_plugin_ui() ``` 3. **翻译键管理**： - 创建 `translation_keys.gd` 脚本统一管理所有翻译键： ```gdscript class_name PluginTranslationKeys static var PLUGIN_NAME = "PLUGIN_NAME" static var PLUGIN_BUTTON = "PLUGIN_BUTTON" # 其他键... ``` - 使用方式：`tr(PluginTranslationKeys.PLUGIN_NAME)` 4. **自动提取翻译键**： 使用 Godot 的字符串提取工具： ```bash # 从插件目录提取所有tr()字符串 godot --doctool res://addons/your_plugin/ --extract-to res://addons/your_plugin/translations/keys.pot ``` ## 测试建议 1. **多语言测试**： - 在编辑器设置中切换不同语言 - 验证插件界面是否相应更新 2. **边界情况测试**： - 测试缺少翻译键时的回退行为 - 测试特殊字符和长文本的显示 3. **性能测试**： - 加载大量翻译文件时的性能 - 频繁切换语言时的响应速度 ## 常见问题解决 - **翻译不更新**： 确保在 `_enter_tree()` 中正确加载翻译，并监听编辑器设置变化 - **与其他插件冲突**： 使用唯一前缀命名翻译键，避免键名冲突 - **编辑器语言不匹配**： 使用 `EditorInterface.get_editor_settings().get_setting("interface/editor/editor_language")` 获取编辑器当前语言