Missing documentation on TranslationPO and related translation context functionality.

[awardell]

Godot 4.x

The Issue

There is a class TranslationPO. It has been around for maybe 3 years, and yet there is zero mention of it in the docs.

A user posted on the Godot forums here that they could not understand how "context" was supposed to be utilized in localization, although it was clear that it is the feature they need. The only explanation of "context" in the docs is a small paragraph and example in the page on Internationalizing games.

Translation contexts

If you're using plain English as source strings (rather than message codes LIKE_THIS), you may run into ambiguities when you have to translate the same English string to different strings in certain target languages. You can optionally specify a translation context to resolve this ambiguity and allow target languages to use different strings, even though the source string is identical:

# "Close", as in an action (to close something).
button.set_text(tr("Close", "Actions"))

"Close", as in a distance (opposite of "far").

distance_label.set_text(tr("Close", "Distance"))

I went hunting through the engine code until I found [this warning in Translation.cpp](https://github.com/godotengine/godot/blob/4c96e9676b66d0cc9a25022b019b78f4c20ddc60/core/string/translation.cpp#L116):
`WARN_PRINT("Translation class doesn't handle context. Using context in get_message() on a Translation instance is probably a mistake. \nUse a derived Translation class that handles context, such as TranslationPO class");` This was the first I had heard of the class. I searched the docs for the class and found nothing. I searched Google and found only the translation_po files on github. It's not hooked up to the ClassDB nor in any XML files in the engine repository. I and others have no idea how to use it.

It seems very bizarre to me that in the 3 years since that class was written, either no one has used "context" in their games, or, even less likely, that no one has needed to look up how to use "context" in order to use it.

### This Proposal

There needs to be documentation of TranslationPO and its usage. If it is indeed the only way to utilize translation context, then the explanation for context needs to link to documentation for TranslationPO in addition to being greatly expounded upon. It should be made clear to users what steps they need to take to generate a TranslationPO and to utilize context. If there are external software related to TranslationPO, then they at least need to be alluded to even if they are something proprietary. A reader should be able to fully understand what they need to do with their data in order to serve translations with context.

[awardell]

@SkyLucilfer it appears you are the author of the translation_po files.

[robcbryant]

I would also be very interested in understanding this. As best I can tell--you may be able to add context through gettext formats but not CSV:

https://docs.godotengine.org/en/stable/tutorials/i18n/localization_using_gettext.html#doc-localization-using-gettext

Also tried looking at: https://github.com/godotengine/godot/blob/42e5b3ac2da07d2105c775977b39e6949c723ded/core/io/resource_loader.cpp#L1117

To understand how it was loading the CSV, but to no avail so I moved on to the editors actual import process:

https://github.com/godotengine/godot/blob/42e5b3ac2da07d2105c775977b39e6949c723ded/editor/localization_editor.cpp#L609

This proved also unhelpful to me because I'm not great at C++ and 1 to 2 letter variable names. My goal was to try and understand HOW Godot is reading the CSV files to see how where within the CSV it's looking for a cell/column that has context. I failed. I welcome someone else to try however.

EDIT: https://github.com/godotengine/godot/blob/42e5b3ac2da07d2105c775977b39e6949c723ded/editor/import/resource_importer_csv_translation.cpp#L75

I also tracked the above down--it would seem like, to the best of my understanding, that when the CSV is imported there is no context being looked for. Just the ID and locale columns: specifically at this line in the loop: https://github.com/godotengine/godot/blob/42e5b3ac2da07d2105c775977b39e6949c723ded/editor/import/resource_importer_csv_translation.cpp#L130C5-L130C79