Add a role for identifying and auto-translating properties #8890
Description
Your Godot version:
4.2
Issue description:
There are lots of places in the docs where properties are referenced. Some link to the Class Reference (if the section is more code-oriented), like here:
Some are merely described as plain text (if the section is more editor-related), like here:
The latter part presents some problems:
- If a property is renamed in the editor, the manual will go out of sync in many places which needs to be manually tracked down and fixed. In case of typos, text search won't help and the property change will be missed.
- The property in the docs text has to be manually translated and kept in sync with the translated version of the editor properties in case they change.
- It is preferable to display the translated property in the docs instead of the English one. This can make it hard for the reader to identify the corresponding English property name (e.g. for code access). Having access to both the native and the original English translation can help understanding a technical term if the English version is more familiar than the localized one.
- Currently, there is no common formatting rule for properties. Sometimes they are plain text and sometimes they are bold. Unifying this is one issue, but additionally, later changes to the format in all places would be a lot of work.
Proposed Solution
It would be nice if we could add support for a role to the docs that identifies a property. This would solve the problems descibed above:
- During docs compile time, it can be ensured that the tagged property actually exists under that name and a warning is printed if there is no match
- The translators would leave the tagged property untranslated, and the translation would be filled in automatically during docs compilation.
- When building the translation of the tagged property, a tooltip is added to the docs that displays the English name of a property, so the user can look it up conveniently.
- The property can be uniquely formatted, possibly in a way that makes it more explicit that this is a property (a better way than just using bold)
Implementation Suggestion
- Add a custom Sphinx role
:property:`name`
- In the English docs, the
name
argument will be checked against the property in the godot repo and formatted to some standard. If missing, an error will be raised - In the Translated docs, the string will be checked against with the language's po file and replaced by the translation, adding a tooltip. If missing, an error will be raised
Example:
- rst:
This is some text about the :property:`Alpha Scissor` property
- converted:
This is some text about the **Alpha Scissor** property
- converted de:
Dies ist ein Text über die :abbr:`**Alpha-Schere** (Englisch: Alpha Scissor)`-Property
.
Caveats
One problem that needs to be discussed is how to draw the link from the docs to the godot main repo. This approach might require adding the godot main repo to the docs repo as a submodule, which might be a bit heavy.
Alternatively, a loose link to the main repo could be established to a main repo checked out elsewhere, or the relevant string files could be copied manually, but these don't seem like very clean solutions, especially for version management.
Alternative Thought 1
This could be extendended to Editor strings :editor:`Project Settings...`
. Menu strings could be expressed like this: :editor:`Project > Project Settings...`
where individual substrings would be extracted via script. This would ease writing the docs code, so that the menu string parts won't have to get individual roles.
Alternative Thought 2
A toned down version of this proposal would be to just add the roles for consistent formatting but without heavy attachment of any other repo via submodule. This would still allow referencing other repos via scripts, but it would be more of a loose coupling.
The translation part would then not happen automatically but in the form of a check, which could be executed manually in case a language wants to use this feature. In this scenario, a script would check if the translated string in the docs is consistent with the translation in the properties or the editor.
This second thought would split this proposal into two parts:
- Adding roles for properties and editor strings to aid reviewability and consistent formatting
- (optional) Auto-translation of these strings the docs
Activity