X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/611bed35118d838abdec90a23a90e492a6cc75d1..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/translation.h

diff --git a/interface/wx/translation.h b/interface/wx/translation.h
index fc1c35a229..dcd46bed10 100644
--- a/interface/wx/translation.h
+++ b/interface/wx/translation.h
@@ -2,8 +2,7 @@
 // Name:        translation.h
 // Purpose:     wxTranslation class
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -30,7 +29,7 @@
 
     @since 2.9.1
 
-    @see wxLocale
+    @see wxLocale, wxTranslationsLoader, wxFileTranslationsLoader
  */
 class wxTranslations
 {
@@ -79,6 +78,64 @@ public:
      */
     void SetLanguage(const wxString& lang);
 
+    /**
+        Returns list of all translations of @a domain that were found.
+
+        This method can be used e.g. to populate list of application's
+        translations offered to the user. To do this, pass the app's main
+        catalog as @a domain.
+
+        @see GetBestTranslation()
+     */
+    wxArrayString GetAvailableTranslations(const wxString& domain) const;
+
+    /**
+        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(); modern operation systems (Windows
+        Vista+, OS X) have separate language and regional (= 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
+     */
+    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(); modern operation systems (Windows
+        Vista+, OS X) have separate language and regional (= 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
+     */
+    wxString GetBestTranslation(const wxString& domain,
+                                const wxString& msgIdLanguage = "en");
+
     /**
         Add standard wxWidgets catalogs ("wxstd" and possible port-specific
         catalogs).
@@ -244,8 +301,8 @@ public:
 class wxTranslationsLoader
 {
 public:
-    /// Constructor
-    wxTranslationsLoader() {}
+    /// Trivial default constructor.
+    wxTranslationsLoader();
 
     /**
         Called to load requested catalog.
@@ -265,6 +322,11 @@ public:
      */
     virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
                                       const wxString& lang) = 0;
+
+    /**
+        Implements wxTranslations::GetAvailableTranslations().
+     */
+    virtual wxArrayString GetAvailableTranslations(const wxString& domain) const = 0;
 };
 
 /**
@@ -274,9 +336,11 @@ public:
     This is the default unless you change the loader with
     wxTranslations::SetLoader().
 
-    Catalogs are searched for in standard places (current directory first, then
-    the system one), but you may also prepend additional directories to the
-    search path with AddCatalogLookupPathPrefix().
+    Catalogs are searched for in standard places (system locales directory,
+    `LC_PATH` on Unix systems, Resources subdirectory of the application bundle
+    on OS X, executable's directory on Windows), but you may also prepend
+    additional directories to the search path with
+    AddCatalogLookupPathPrefix().
 
     @since 2.9.1
  */
@@ -285,7 +349,7 @@ class wxFileTranslationsLoader : public wxTranslationsLoader
 public:
     /**
         Add a prefix to the catalog lookup path: the message catalog files will
-        be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
+        be looked up under prefix/lang/LC_MESSAGES and prefix/lang directories
         (in this order).
 
         This only applies to subsequent invocations of
@@ -452,10 +516,10 @@ public:
     This function calls wxTranslations::GetString().
 
     @note This function is not suitable for literal strings in Unicode builds
-          since the literal strings must be enclosed into _T() or wxT() macro
-          which makes them unrecognised by @c xgettext, and so they are not
-          extracted to the message catalog. Instead, use the _() and wxPLURAL()
-          macro for all literal strings.
+          since the literal strings must be enclosed in wxT() macro which makes
+          them unrecognised by @c xgettext, and so they are not extracted to
+          the message catalog. Instead, use the _() and wxPLURAL() macro for
+          all literal strings.
 
     @see wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&)
 
@@ -491,13 +555,13 @@ const wxString& wxGetTranslation(const wxString& string,
                                  const wxString& domain = wxEmptyString);
 
 /**
+    Macro to be used around all literal strings that should be translated.
+
     This macro expands into a call to wxGetTranslation(), so it marks the
     message for the extraction by @c xgettext just as wxTRANSLATE() does, but
     also returns the translation of the string for the current locale during
     execution.
 
-    Don't confuse this with _T()!
-
     @header{wx/intl.h}
 */
 const wxString& _(const wxString& string);