Merge remote-tracking branch 'upstream/master' into export_file-breaking-change-doc

getting_started/step_by_step/nodes_and_scenes.rst

@@ -48,7 +48,7 @@ Scenes allow you to structure your game's code however you want. You can
 **compose nodes** to create custom and complex node types, like a game character
 that runs and jumps, a life bar, a chest with which you can interact, and more.
 
-.. image:: img/nodes_and_scenes_3d_scene_example.png
+.. image:: img/nodes_and_scenes_3d_scene_example.webp
 
 The Godot editor essentially is a **scene editor**. It has plenty of tools for
 editing 2D and 3D scenes, as well as user interfaces. A Godot project can

getting_started/step_by_step/scripting_languages.rst

@@ -45,7 +45,7 @@ language specifically for Godot and the needs of game developers. It has a
 lightweight and straightforward syntax and provides the tightest integration
 with Godot.
 
-.. image:: img/scripting_gdscript.png
+.. image:: img/scripting_gdscript.webp
 
 For C#, you will need an external code editor like
 `VSCode <https://code.visualstudio.com/>`_ or Visual Studio. While C# support is

getting_started/step_by_step/signals.rst

@@ -271,16 +271,16 @@ In the Scene dock, right-click on the Sprite2D node and add a new child node.
 Search for Timer and add the corresponding node. Your scene should now look like
 this.
 
-.. image:: img/signals_15_scene_tree.png
+.. image:: img/signals_15_scene_tree.webp
 
 With the Timer node selected, go to the Inspector and enable the **Autostart**
 property.
 
-.. image:: img/signals_18_timer_autostart.png
+.. image:: img/signals_18_timer_autostart.webp
 
 Click the script icon next to Sprite2D to jump back to the scripting workspace.
 
-.. image:: img/signals_16_click_script.png
+.. image:: img/signals_16_click_script.webp
 
 We need to do two operations to connect the nodes via code:
 

tutorials/3d/procedural_geometry/surfacetool.rst

@@ -15,6 +15,10 @@ Attributes are added before each vertex is added:
 .. tabs::
  .. code-tab:: gdscript GDScript
 
+    var st = SurfaceTool.new()
+
+    st.begin(Mesh.PRIMITIVE_TRIANGLES)
+
     st.set_normal() # Overwritten by normal below.
     st.set_normal() # Added to next vertex.
     st.set_color() # Added to next vertex.
@@ -29,16 +33,20 @@ Attributes are added before each vertex is added:
     st.AddVertex(); // Captures normal and color above.
     st.SetNormal(); // Normal never added to a vertex.
 
-When finished generating your geometry with the :ref:`SurfaceTool <class_surfacetool>`
+When finished generating your geometry with the :ref:`SurfaceTool <class_surfacetool>`,
 call ``commit()`` to finish generating the mesh. If an :ref:`ArrayMesh <class_ArrayMesh>` is passed
-to ``commit()`` then it appends a new surface to the end of the ArrayMesh. While if nothing is passed
+to ``commit()``, then it appends a new surface to the end of the ArrayMesh. While if nothing is passed
 in, ``commit()`` returns an ArrayMesh.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
 
+    # Add surface to existing ArrayMesh.
     st.commit(mesh)
-    # Or:
+
+    # -- Or Alternatively --
+
+    # Create new ArrayMesh.
     var mesh = st.commit()
 
  .. code-tab:: csharp
@@ -47,7 +55,7 @@ in, ``commit()`` returns an ArrayMesh.
     // Or:
     var mesh = st.Commit();
 
-Code creates a triangle with indices
+The code below creates a triangle without indices.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -97,14 +105,37 @@ Code creates a triangle with indices
     var mesh = st.Commit();
 
 You can optionally add an index array, either by calling ``add_index()`` and adding
-vertices to the index array or by calling ``index()`` which shrinks the vertex array
-to remove duplicate vertices.
+vertices to the index array manually, or by calling ``index()`` once,
+which generates the index array automatically and
+shrinks the vertex array to remove duplicate vertices.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
+    # Suppose we have a quad defined by 6 vertices as follows
+    st.add_vertex(Vector3(-1, 1, 0))
+    st.add_vertex(Vector3(1, 1, 0))
+    st.add_vertex(Vector3(-1, -1, 0))
+
+    st.add_vertex(Vector3(1, 1, 0))
+    st.add_vertex(Vector3(1, -1, 0))
+    st.add_vertex(Vector3(-1, -1, 0))
+
+    # We can make the quad more efficient by using an index array and only utilizing 4 vertices
+
+    # Suppose we have a quad defined by 6 vertices as follows
+    st.add_vertex(Vector3(-1, 1, 0))
+    st.add_vertex(Vector3(1, 1, 0))
+    st.add_vertex(Vector3(-1, -1, 0))
+
+    st.add_vertex(Vector3(1, 1, 0))
+    st.add_vertex(Vector3(1, -1, 0))
+    st.add_vertex(Vector3(-1, -1, 0))
+
+    # We can make the quad more efficient by using an index array and only utilizing 4 vertices
 
     # Creates a quad from four corner vertices.
-    # add_index does not need to be called before add_vertex.
+    # add_index() can be called before or after add_vertex()
+    # since it's not an attribute of a vertex itself.
     st.add_index(0)
     st.add_index(1)
     st.add_index(2)
@@ -113,7 +144,7 @@ to remove duplicate vertices.
     st.add_index(3)
     st.add_index(2)
 
-    # Alternatively:
+    # Alternatively we can use ``st.index()`` which will create the quad for us and remove the duplicate vertices
     st.index()
 
  .. code-tab:: csharp
@@ -161,12 +192,15 @@ normals set already.
     st.generate_normals()
     st.generate_tangents()
 
+    st.commit(mesh)
+
  .. code-tab:: csharp
     
     st.GenerateNormals();
     st.GenerateTangents();
 
-By default, when generating normals, they will be calculated on a per-face basis. If you want
-smooth vertex normals, when adding vertices, call ``add_smooth_group()``. ``add_smooth_group()``
-needs to be called while building the geometry, e.g. before the call to ``add_vertex()``
-(if non-indexed) or ``add_index()`` (if indexed).
+By default, when generating normals, they will be calculated on a per-vertex basis (i.e. they will
+be "smooth normals"). If you want flat vertex normals (i.e. a single normal vector per face), when
+adding vertices, call ``add_smooth_group(i)`` where ``i`` is a unique number per vertex.
+``add_smooth_group()`` needs to be called while building the geometry, e.g. before the call to
+``add_vertex()``.

tutorials/i18n/localization_using_gettext.rst

@@ -1,7 +1,7 @@
 .. _doc_localization_using_gettext:
 
-Localization using gettext
-==========================
+Localization using gettext (PO files)
+=====================================
 
 In addition to importing translations in
 :ref:`CSV format <doc_localization_using_spreadsheets>`, Godot also
@@ -13,27 +13,35 @@ supports loading translation files written in the GNU gettext format
           It's written with C projects in mind, but much of the advice
           also applies to Godot (with the exception of ``xgettext``).
 
+          For the complete documentation, see `GNU Gettext <https://www.gnu.org/software/gettext/manual/gettext.html>`_.
+
 Advantages
 ----------
 
 - gettext is a standard format, which can be edited using any text editor
-  or GUI editors such as `Poedit <https://poedit.net/>`_.
+  or GUI editors such as `Poedit <https://poedit.net/>`_. This can be significant
+  as it provides a lot of tools for translators, such as marking outdated
+  strings, finding strings that haven't been translated etc. 
+- gettext supports plurals and context.
 - gettext is supported by translation platforms such as
   `Transifex <https://www.transifex.com/>`_ and `Weblate <https://weblate.org/>`_,
   which makes it easier for people to collaborate to localization.
-- Compared to CSV, gettext works better with version control systems like Git,
+- Compared to CSV, gettext files work better with version control systems like Git,
   as each locale has its own messages file.
-- Multiline strings are more convenient to edit in gettext files compared
+- Multiline strings are more convenient to edit in gettext PO files compared
   to CSV files.
 
 Disadvantages
 -------------
 
-- gettext is a more complex format than CSV and can be harder to grasp for
+- gettext PO files have a more complex format than CSV and can be harder to grasp for
   people new to software localization.
 - People who maintain localization files will have to install gettext tools
   on their system. However, as Godot supports using text-based message files
   (``.po``), translators can test their work without having to install gettext tools.
+- gettext PO files usually use English as the base language. Translators will use 
+  this base language to translate to other languages. You could still user other 
+  languages as the base language, but this is not common.
 
 Installing gettext tools
 ------------------------
@@ -53,6 +61,9 @@ install them.
 - **Linux:** On most distributions, install the ``gettext`` package from
   your distribution's package manager.
 
+For a GUI tool you can get Poedit from its `Official website <https://poedit.net/>`_.
+The basic version is open source and available under the MIT license.
+
 Creating the PO template
 ------------------------
 
@@ -193,8 +204,10 @@ saved as ``fr.po~`` in this example), remove the ``--backup=none`` argument.
 Checking the validity of a PO file or template
 ----------------------------------------------
 
-It is possible to check whether a gettext file's syntax is valid by running
-the command below:
+It is possible to check whether a gettext file's syntax is valid.
+
+If you open with Poeditor, it will display the appropriate warnings if there's some
+syntax errors. You can also verify by running the gettext command below:
 
 .. code-block:: shell
 
@@ -266,3 +279,46 @@ These comments must be placed either on the same line as the recognized pattern
     # TRANSLATORS: This is a reference to Lewis Carroll's poem "Jabberwocky",
     # make sure to keep this as it is important to the plot.
     say(tr("He took his vorpal sword in hand. The end?"))
+
+Using context
+-------------
+
+The ``context`` parameter can be used to differentiate the situation where a translation
+is used, or to differentiate polysemic words (words with multiple meanings).
+
+For example: 
+
+::
+
+    tr("Start", "Main Menu")
+    tr("End", "Main Menu")
+    tr("Shop", "Main Menu")
+    tr("Shop", "In Game")
+
+Updating PO files
+-----------------
+
+Some time or later, you'll add new content to our game, and there will be new strings that need to be translated. When this happens, you'll
+need to update the existing PO files to include the new strings.
+
+First, generate a new POT file containing all the existing strings plus the newly added strings. After that, merge the existing 
+PO files with the new POT file. There are two ways to do this:
+
+- Use a gettext editor, and it should have an option to update a PO file from a POT file.
+
+- Use the gettext ``msgmerge`` tool:
+
+.. code-block:: shell
+
+    # The order matters: specify the message file *then* the PO template!
+    msgmerge --update --backup=none fr.po messages.pot
+
+If you want to keep a backup of the original message file (which would be saved as ``fr.po~`` in this example), 
+remove the ``--backup=none`` argument.
+
+POT generation custom plugin
+----------------------------
+
+If you have any extra file format to deal with, you could write a custom plugin to parse and and extract the strings from the custom file. 
+This custom plugin will extract the strings and write into the POT file when you hit **Generate POT**. To learn more about how to
+create the translation parser plugin, see :ref:`EditorTranslationParserPlugin <class_EditorTranslationParserPlugin>`.

tutorials/migrating/upgrading_to_godot_4.4.rst

@@ -61,10 +61,9 @@ Method ``standardize_locale`` adds a new ``add_defaults`` optional parameter
 
     The behavior of ``@export_file`` changed in Godot 4.4. When assigning a new value
     from the Inspector, the path is now stored and returned as a ``uid://`` reference
-    instead of the traditional ``res://`` path. This is a **breaking change** and may
+    instead of the traditional ``res://`` path(`GH-97912`_). This is a **breaking change** and may
     cause issues if you're expecting ``res://``-based paths in scripts or serialized
-    files. This change was introduced in
-    `PR #105414 <https://github.com/godotengine/godot/pull/105414>`_.
+    files.
 
     For example, exported arrays of files may now contain a mix of ``uid://`` and
     ``res://`` paths, especially if they were partially edited in the Inspector.
@@ -226,6 +225,7 @@ Android
 .. _GH-95212: https://github.com/godotengine/godot/pull/95212
 .. _GH-95126: https://github.com/godotengine/godot/pull/95126
 .. _GH-97449: https://github.com/godotengine/godot/pull/97449
+.. _GH-97912: https://github.com/godotengine/godot/pull/97912
 .. _GH-98670: https://github.com/godotengine/godot/pull/98670
 .. _GH-98918: https://github.com/godotengine/godot/pull/98918
 .. _GH-98972: https://github.com/godotengine/godot/pull/98972

tutorials/plugins/running_code_in_the_editor.rst

@@ -264,8 +264,7 @@ angle add a setter ``set(new_speed)`` which is executed with the input from the
     Code from other nodes doesn't run in the editor. Your access to other nodes
     is limited. You can access the tree and nodes, and their default properties,
     but you can't access user variables. If you want to do so, other nodes have
-    to run in the editor too. Autoload nodes cannot be accessed in the editor at
-    all.
+    to run in the editor too.
 
 Getting notified when resources change
 --------------------------------------