Merge branch 'msw-add-def-catalog'

Fix AddStdCatalog() under MSW and add functions without msg ID fallback.

See #23930.

interface/wx/intl.h

@@ -390,7 +390,10 @@ public:
     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
 
     /**
-        Calls wxTranslations::AddCatalog(const wxString&, wxLanguage, const wxString&).
+        Calls wxTranslations::AddCatalog(const wxString&, const wxString&).
+
+        @deprecated This overload shouldn't be used any longer as @a
+        msgIdCharset is just ignored, please omit it.
     */
     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage,
                     const wxString& msgIdCharset);

interface/wx/translation.h

@@ -89,6 +89,18 @@ public:
      */
     wxArrayString GetAvailableTranslations(const wxString& domain) const;
 
+    /**
+        Returns the best available translation for the required language.
+
+        For wxLANGUAGE_DEFAULT, this function returns the available translation
+        best matching one of wxUILocale::GetPreferredUILanguages(). Otherwise
+        it simply returns the language set with SetLanguage() if it's available
+        or empty string otherwise.
+
+        @since 3.3.0
+     */
+    wxString GetBestAvailableTranslation(const wxString& domain);
+
     /**
         Returns the best UI language for the @a domain.
 
@@ -98,6 +110,13 @@ public:
         wxLocale::GetSystemLanguage() as operating systems have separate
         language and regional (i.e. locale) settings.
 
+        Please note that that this function may return the language
+        corresponding to @a msgIdLanguage if this language is considered to be
+        acceptable, i.e. is part of wxUILocale::GetPreferredUILanguages(),
+        indicating that it is fine not to use translations at all on this
+        system. If this is undesirable, GetBestAvailableTranslation() should be
+        used which doesn't consider the messages ID language as being available.
+
         @param domain
             The catalog domain to look for.
 
@@ -113,25 +132,7 @@ public:
     wxString GetBestTranslation(const wxString& domain, wxLanguage msgIdLanguage);
 
     /**
-        Returns the best UI language for the @a domain.
-
-        The language is determined from the preferred UI language or languages
-        list the user configured in the OS. Notice that this may or may not
-        correspond to the default @em locale as obtained from
-        wxLocale::GetSystemLanguage() as operating systems have separate
-        language and regional (i.e. locale) settings.
-
-        @param domain
-            The catalog domain to look for.
-
-        @param msgIdLanguage
-            Specifies the language of "msgid" strings in source code
-            (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
-
-        @return Language code if a suitable match was found, empty string
-                otherwise.
-
-        @since 2.9.5
+        @overload
      */
     wxString GetBestTranslation(const wxString& domain,
                                 const wxString& msgIdLanguage = "en");
@@ -142,14 +143,14 @@ public:
 
         @return @true if a suitable catalog was found, @false otherwise
 
-        @see AddCatalog()
+        @see AddAvailableCatalog()
      */
     bool AddStdCatalog();
 
     /**
         Add a catalog for use with the current locale.
 
-        By default, it is searched for in standard places (see
+        By default, the catalog is searched for in standard places (see
         wxFileTranslationsLoader), but you may also prepend additional
         directories to the search path with
         wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
@@ -157,6 +158,28 @@ public:
         All loaded catalogs will be used for message lookup by GetString() for
         the current locale.
 
+        @return
+            @true if catalog was successfully loaded, @false otherwise, usually
+            because it wasn't found. Note that unlike AddCatalog() this
+            function returns @false even if the language of the original
+            strings (usually English) can be used directly, i.e. its return
+            value only indicates that there are no catalogs available for the
+            selected or system-default languages, but is not necessarily an
+            error if no translations are needed in the first place.
+
+        @since 3.3.0
+     */
+    bool AddAvailableCatalog(const wxString& domain);
+
+    /**
+        Add a catalog for use with the current locale or fall back to the
+        original messages language.
+
+        This function behaves like AddAvailableCatalog() but also checks if the
+        strings used in the program, written in @a msgIdLanguage, can be used
+        without any translations on the current system and also returns @true
+        in this case, unlike AddAvailableCatalog().
+
         By default, i.e. if @a msgIdLanguage is not given, @c msgid strings are assumed
         to be in English and written only using 7-bit ASCII characters.
         If you have to deal with non-English strings or 8-bit characters in the
@@ -173,47 +196,21 @@ public:
             code are used instead.
 
         @return
-            @true if catalog was successfully loaded, @false otherwise (which might
-            mean that the catalog is not found or that it isn't in the correct format).
+            @true if catalog was successfully loaded or loading it is
+            unnecessary because the original messages can be used directly,
+            @false otherwise (which might mean that the catalog is not found or
+            that it isn't in the correct format).
      */
     bool AddCatalog(const wxString& domain,
                     wxLanguage msgIdLanguage = wxLANGUAGE_ENGLISH_US);
 
-    /**
-        Same as AddCatalog(const wxString&, wxLanguage), but takes two
-        additional arguments, @a msgIdLanguage and @a msgIdCharset.
-
-        This overload is only available in non-Unicode build.
-
-        @param domain
-            The catalog domain to add.
-
-        @param msgIdLanguage
-            Specifies the language of "msgid" strings in source code
-            (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
-            It is used if AddCatalog() cannot find any catalog for current language:
-            if the language is same as source code language, then strings from source
-            code are used instead.
-
-        @param msgIdCharset
-            Lets you specify the charset used for msgids in sources
-            in case they use 8-bit characters (e.g. German or French strings).
-
-        @return
-            @true if catalog was successfully loaded, @false otherwise (which might
-            mean that the catalog is not found or that it isn't in the correct format).
-     */
-    bool AddCatalog(const wxString& domain,
-                    wxLanguage msgIdLanguage,
-                    const wxString& msgIdCharset);
-
     /**
         Check if the given catalog is loaded, and returns @true if it is.
 
         According to GNU gettext tradition, each catalog normally corresponds to
         'domain' which is more or less the application name.
 
-        @see AddCatalog()
+        @see AddAvailableCatalog()
      */
     bool IsLoaded(const wxString& domain) const;
 
@@ -348,7 +345,7 @@ public:
         (in this order).
 
         This only applies to subsequent invocations of
-        wxTranslations::AddCatalog().
+        wxTranslations::AddAvailableCatalog().
     */
     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 };
@@ -358,8 +355,7 @@ public:
     resources.
 
     If you wish to store translation MO files in resources, you have to
-    enable this loader before calling wxTranslations::AddCatalog() or
-    wxLocale::AddCatalog():
+    enable this loader before calling wxTranslations::AddAvailableCatalog():
 
     @code
     wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader);