godot-docs/classes/class_editortranslationparserplugin.rst

:github_url: hide

.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/EditorTranslationParserPlugin.xml.

.. _class_EditorTranslationParserPlugin:

EditorTranslationParserPlugin
=============================

**Inherits:** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`

Plugin for adding custom parsers to extract strings that are to be translated from custom files (.csv, .json etc.).

.. rst-class:: classref-introduction-group

Description
-----------

**EditorTranslationParserPlugin** is invoked when a file is being parsed to extract strings that require translation. To define the parsing and string extraction logic, override the :ref:`_parse_file<class_EditorTranslationParserPlugin_private_method__parse_file>` method in script.

Add the extracted strings to argument ``msgids`` or ``msgids_context_plural`` if context or plural is used.

When adding to ``msgids_context_plural``, you must add the data using the format ``["A", "B", "C"]``, where ``A`` represents the extracted string, ``B`` represents the context, and ``C`` represents the plural version of the extracted string. If you want to add only context but not plural, put ``""`` for the plural slot. The idea is the same if you only want to add plural but not context. See the code below for concrete examples.

The extracted strings will be written into a POT file selected by user under "POT Generation" in "Localization" tab in "Project Settings" menu.

Below shows an example of a custom parser that extracts strings from a CSV file to write into a POT.


.. tabs::

 .. code-tab:: gdscript

    @tool
    extends EditorTranslationParserPlugin
    
    func _parse_file(path, msgids, msgids_context_plural):
        var file = FileAccess.open(path, FileAccess.READ)
        var text = file.get_as_text()
        var split_strs = text.split(",", false)
        for s in split_strs:
            msgids.append(s)
            #print("Extracted string: " + s)
    
    func _get_recognized_extensions():
        return ["csv"]

 .. code-tab:: csharp

    using Godot;
    
    [Tool]
    public partial class CustomParser : EditorTranslationParserPlugin
    {
        public override void _ParseFile(string path, Godot.Collections.Array<string> msgids, Godot.Collections.Array<Godot.Collections.Array> msgidsContextPlural)
        {
            using var file = FileAccess.Open(path, FileAccess.ModeFlags.Read);
            string text = file.GetAsText();
            string[] splitStrs = text.Split(",", allowEmpty: false);
            foreach (string s in splitStrs)
            {
                msgids.Add(s);
                //GD.Print($"Extracted string: {s}");
            }
        }
    
        public override string[] _GetRecognizedExtensions()
        {
            return new string[] { "csv" };
        }
    }



To add a translatable string associated with context or plural, add it to ``msgids_context_plural``:


.. tabs::

 .. code-tab:: gdscript

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

 .. code-tab:: csharp

    // This will add a message with msgid "Test 1", msgctxt "context", and msgid_plural "test 1 plurals".
    msgidsContextPlural.Add(new Godot.Collections.Array{"Test 1", "context", "test 1 Plurals"});
    // This will add a message with msgid "A test without context" and msgid_plural "plurals".
    msgidsContextPlural.Add(new Godot.Collections.Array{"A test without context", "", "plurals"});
    // This will add a message with msgid "Only with context" and msgctxt "a friendly context".
    msgidsContextPlural.Add(new Godot.Collections.Array{"Only with context", "a friendly context", ""});



\ **Note:** If you override parsing logic for standard script types (GDScript, C#, etc.), it would be better to load the ``path`` argument using :ref:`ResourceLoader.load<class_ResourceLoader_method_load>`. This is because built-in scripts are loaded as :ref:`Resource<class_Resource>` type, not :ref:`FileAccess<class_FileAccess>` type. For example:


.. tabs::

 .. code-tab:: gdscript

    func _parse_file(path, msgids, msgids_context_plural):
        var res = ResourceLoader.load(path, "Script")
        var text = res.source_code
        # Parsing logic.
    
    func _get_recognized_extensions():
        return ["gd"]

 .. code-tab:: csharp

    public override void _ParseFile(string path, Godot.Collections.Array<string> msgids, Godot.Collections.Array<Godot.Collections.Array> msgidsContextPlural)
    {
        var res = ResourceLoader.Load<Script>(path, "Script");
        string text = res.SourceCode;
        // Parsing logic.
    }
    
    public override string[] _GetRecognizedExtensions()
    {
        return new string[] { "gd" };
    }



To use **EditorTranslationParserPlugin**, register it using the :ref:`EditorPlugin.add_translation_parser_plugin<class_EditorPlugin_method_add_translation_parser_plugin>` method first.

.. rst-class:: classref-reftable-group

Methods
-------

.. table::
   :widths: auto

   +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | |void|                                            | :ref:`_get_comments<class_EditorTranslationParserPlugin_private_method__get_comments>`\ (\ msgids_comment\: :ref:`Array<class_Array>`\[:ref:`String<class_String>`\], msgids_context_plural_comment\: :ref:`Array<class_Array>`\[:ref:`String<class_String>`\]\ ) |virtual|               |
   +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`PackedStringArray<class_PackedStringArray>` | :ref:`_get_recognized_extensions<class_EditorTranslationParserPlugin_private_method__get_recognized_extensions>`\ (\ ) |virtual| |const|                                                                                                                                                  |
   +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | |void|                                            | :ref:`_parse_file<class_EditorTranslationParserPlugin_private_method__parse_file>`\ (\ path\: :ref:`String<class_String>`, msgids\: :ref:`Array<class_Array>`\[:ref:`String<class_String>`\], msgids_context_plural\: :ref:`Array<class_Array>`\[:ref:`Array<class_Array>`\]\ ) |virtual| |
   +---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Method Descriptions
-------------------

.. _class_EditorTranslationParserPlugin_private_method__get_comments:

.. rst-class:: classref-method

|void| **_get_comments**\ (\ msgids_comment\: :ref:`Array<class_Array>`\[:ref:`String<class_String>`\], msgids_context_plural_comment\: :ref:`Array<class_Array>`\[:ref:`String<class_String>`\]\ ) |virtual| :ref:`🔗<class_EditorTranslationParserPlugin_private_method__get_comments>`

If overridden, called after :ref:`_parse_file<class_EditorTranslationParserPlugin_private_method__parse_file>` to get comments for the parsed entries. This method should fill the arrays with the same number of elements and in the same order as :ref:`_parse_file<class_EditorTranslationParserPlugin_private_method__parse_file>`.

.. rst-class:: classref-item-separator

----

.. _class_EditorTranslationParserPlugin_private_method__get_recognized_extensions:

.. rst-class:: classref-method

:ref:`PackedStringArray<class_PackedStringArray>` **_get_recognized_extensions**\ (\ ) |virtual| |const| :ref:`🔗<class_EditorTranslationParserPlugin_private_method__get_recognized_extensions>`

Gets the list of file extensions to associate with this parser, e.g. ``["csv"]``.

.. rst-class:: classref-item-separator

----

.. _class_EditorTranslationParserPlugin_private_method__parse_file:

.. rst-class:: classref-method

|void| **_parse_file**\ (\ path\: :ref:`String<class_String>`, msgids\: :ref:`Array<class_Array>`\[:ref:`String<class_String>`\], msgids_context_plural\: :ref:`Array<class_Array>`\[:ref:`Array<class_Array>`\]\ ) |virtual| :ref:`🔗<class_EditorTranslationParserPlugin_private_method__parse_file>`

Override this method to define a custom parsing logic to extract the translatable strings.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`
.. |void| replace:: :abbr:`void (No return value.)`