Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

EditorTranslationParserPlugin

继承： RefCounted < Object

用于添加自定义解析器，以从自定义文件（.csv、.json等）提取已翻译的字符串的插件。

描述

当 Godot 解析文件并提取需要翻译的字符串时，EditorTranslationParserPlugin 就会被触发。你需要在脚本中重写 _parse_file() 方法，来定义具体的解析和字符串提取逻辑。

该方法的返回值应该是一个包含多个 PackedStringArray 的 Array，每一个数组对应一条提取出的可翻译字符串。每条数据应包含 [msgid, msgctxt, msgid_plural, comment, source_line]，其中除了 msgid（原文）是必填项外，其他都是可选项。如果填入空字符串，将会被自动忽略。

提取出来的字符串最终会被写入到翻译模板文件中。这个模板文件的路径，可以在“项目设置”菜单的“本地化”标签页下的“模板生成”选项中进行指定。

下面展示了一个自定义解析器的示例，它会从 CSV 文件中提取字符串并写入到翻译模板里。

@tool
extends EditorTranslationParserPlugin

func _parse_file(path):
    var ret: Array[PackedStringArray] = []
    var file = FileAccess.open(path, FileAccess.READ)
    var text = file.get_as_text()
    var split_strs = text.split(",", false)
    for s in split_strs:
        ret.append(PackedStringArray([s]))
        #print("Extracted string: " + s)

    return ret

func _get_recognized_extensions():
    return ["csv"]

要添加一条附带上下文（context）、复数形式（plural）、注释（comment）或源代码行号（source line）的可翻译字符串：

# This will add a message with msgid "Test 1", msgctxt "context", msgid_plural "test 1 plurals", comment "test 1 comment", and source line "7".
ret.append(PackedStringArray(["Test 1", "context", "test 1 plurals", "test 1 comment", "7"]))
# This will add a message with msgid "A test without context" and msgid_plural "plurals".
ret.append(PackedStringArray(["A test without context", "", "plurals"]))
# This will add a message with msgid "Only with context" and msgctxt "a friendly context".
ret.append(PackedStringArray(["Only with context", "a friendly context"]))

注意： 如果你重写了标准脚本类型（比如 GDScript、C# 等）的解析逻辑，最好使用 ResourceLoader.load() 方法来加载 path 参数。这是因为内置脚本（Built-in scripts）在 Godot 里是被当作 Resource（资源）类型来加载的，而不是 FileAccess（文件访问）类型。举个例子：

func _parse_file(path):
    var res = ResourceLoader.load(path, "Script")
    var text = res.source_code
    # Parsing logic.

func _get_recognized_extensions():
    return ["gd"]

或者，插件也可以通过实现 _customize_strings() 方法，来直接修改最终的字符串列表。

如果要使用 EditorTranslationParserPlugin，你需要先通过 EditorPlugin.add_translation_parser_plugin() 方法将它注册到编辑器中。

方法

Array[PackedStringArray]

_customize_strings(strings: Array[PackedStringArray]) virtual const

PackedStringArray

_get_recognized_extensions() virtual const

Array[PackedStringArray]

_parse_file(path: String) virtual

方法说明

Array[PackedStringArray] _customize_strings(strings: Array[PackedStringArray]) virtual const 🔗

解析完所有文件后调用。你可以修改 strings 数组，以向最终的字符串列表中添加或移除条目，修改完成后请将其返回。每个条目都是一个 PackedStringArray，具体格式如 EditorTranslationParserPlugin 描述中所述。

@tool
extends EditorTranslationParserPlugin

func _customize_strings(strings):
    # 添加新字符串。
    strings.append(["Test 1", "context", "test 1 plurals", "test 1 comment"])

    # 移除所有以 $ 开头的字符串。
    strings = strings.filter(func(s): return not s[0].begins_with("$"))

    return strings

PackedStringArray _get_recognized_extensions() virtual const 🔗

获取与该解析器关联的文件扩展名列表，例如 ["csv"]。

Array[PackedStringArray] _parse_file(path: String) virtual 🔗

覆盖该方法，定义自定义解析逻辑以提取可翻译的字符串。