From Godot's Help:

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…

It happens to be the case on the project I'm working on. The incantation to do this is:

# "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"))

So in this case "Actions" and "Distance" are meant to help with context. But Help does not say a word about how is this "context" used, like are there some csv files named "Actions" and "Distance"? How are these files used and what would be in them? Also it seems no one ever used these, all localization tutorials I saw (been researching this from yesterday morning) just skip this part.

Or is this meant to be more like "context for the translator"? I tried typing in everything from path names to node names to resources to random nonsense but… just nothing happens no matter what I type. No errors, no effect on in game translation, nothing. Has anyone used these?

Edit: found it mentioned in an old proposal for Godot 3, the description sounds just about like what I'm dealing with, after which the reply with advised solution is simply

support for translation contexts was implemented in 4.0

…and that's it! Not a word about what is it. Here is the link:
github post

Wow, the documentation for this is REALLY lacking. I went searching through the engine code and found where context is used. It's actually completely ignored by Translation and OptimizedTranslation. It's only used by translation_po

https://github.com/godotengine/godot/blob/master/core/string/translation_po.h
https://github.com/godotengine/godot/blob/master/core/string/translation_po.cpp

This class isn't mentioned anywhere in the docs. It's not set up to auto-generate a doc. Translation doesn't show it as Inherited By, but it is. This seems like such a bizarre oversight. I'm looking through the github repos and no one has ever raised any issue about this. Even the only google search results for godot "translation_po" are just... those files. Are you the first person who has tried to use this? That seems crazy!

I think someone should add an issue to the godot-docs repo. Let me know if you'd prefer me to do it and I'll be glad to.

    Indeed, the English language is extremely imperfect. And assistance in translation is never a bad thing.

    award "Let me know if you'd prefer me to do it and I'll be glad to."
    Please do, since I have no idea how'd I go about it. Thank you for looking into this, I already started thinking I'm overlooking something super obvious or my search engine skills stopped functioning. It's really incredible no one ever used this.

    I tried to understand the linked code, but didn't manage to figure it out: how's this even meant to be used?

        guduq how's this even meant to be used?

        I have no idea either 😐️

          a month later

          From what I can tell, the context makes no difference. It seems to take the 'last' definition for a particular key and use that as the translation.

          For example, I lookup the same key with different context.
          title.Text = Tr(card.Name, "CardNames");
          details.Text = Tr(card.Name, "CardDetails");

          My expectation would be that the lookup would be taking from the corresponding file matching context.

          What actually happens is, two of the cards take their titles from the CardNames.en.translation (I don't have those keys defined in the CardDetails.en.translation). For the right card which has key ShockingTouch, the text is replaced from the CardDetails, the name in CardNames is ignored.