added wxPLURAL() macro

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@34496 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -8,6 +8,7 @@ wxWidgets Change Log - For more verbose changes, see the manual
 All:
 
 - Added wxLaunchDefaultBrowser.
+- Added wxPLURAL() macro in addition to _() (Jonas Rydberg)
 
 All (GUI):
 

docs/latex/wx/function.tex

@@ -251,6 +251,7 @@ the corresponding topic.
 \helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw}\\
 \helpref{wx\_static\_cast}{wxstaticcastraw}\\
 \helpref{\_}{underscore}\\
+\helpref{wxPLURAL}{wxplural}\\
 \helpref{\_T}{underscoret}
 
 
@@ -1504,17 +1505,27 @@ as wxGetTranslation.
 
 The second form is used when retrieving translation of string that has
 different singular and plural form in English or different plural forms in some
-other language. It takes two extra arguments: \arg{str}
-parameter must contain the singular form of the string to be converted.
-It is also used as the key for the search in the catalog.
-The \arg{strPlural} parameter is the plural form (in English).
-The parameter \arg{n} is used to determine the plural form.  If no
-message catalog is found \arg{str} is returned if `n == 1',
+other language. It takes two extra arguments: as above, \arg{str} 
+parameter must contain the singular form of the string to be converted and
+is used as the key for the search in the catalog. The \arg{strPlural} parameter
+is the plural form (in English). The parameter \arg{n} is used to determine the
+plural form.  If no message catalog is found \arg{str} is returned if `n == 1',
 otherwise \arg{strPlural}.
-See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} for additional information on plural forms handling.
+
+See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} 
+for additional information on plural forms handling. For a shorter alternative
+see the \helpref{wxPLURAL()}{wxplural} macro.
 
 Both versions call \helpref{wxLocale::GetString}{wxlocalegetstring}.
 
+Note that this function is not suitable for literal strings in Unicode
+builds, since you the literal strings must be enclosed into 
+\helpref{\_T()}{underscoret} or \helpref{wxT}{wxt} macro which makes them
+unrecognised by \texttt{xgettext}, and so they are not extracted to the message
+catalog. Instead, use the \helpref{\_()}{underscore} and 
+\helpref{wxPLURAL}{wxplural} macro for all literal strings.
+
+
 \membersection{::wxIsEmpty}\label{wxisempty}
 
 \func{bool}{wxIsEmpty}{\param{const char *}{ p}}
@@ -1688,6 +1699,14 @@ the string for the current locale during execution.
 Don't confuse this macro with \helpref{\_T()}{underscoret}!
 
 
+\membersection{wxPLURAL}\label{wxplural}
+
+\func{const wxChar *}{wxPLURAL}{\param{const char *}{sing}, \param{const char *}{plur}, \param{size\_t}{n}}
+
+This macro is identical to \helpref{\_()}{underscore} but for the plural variant
+of \helpref{wxGetTranslation}{wxgettranslation}.
+
+
 \membersection{\_T}\label{underscoret}
 
 \func{wxChar}{\_T}{\param{char }{ch}}

include/wx/intl.h

@@ -33,10 +33,11 @@
 // ----------------------------------------------------------------------------
 
 // gettext() style macros (notice that xgettext should be invoked with
-// --keyword="_" --keyword="wxGetTranslation:1,2" options
+// --keyword="_" --keyword="wxPLURAL:1,2" options
 // to extract the strings from the sources)
 #ifndef WXINTL_NO_GETTEXT_MACRO
-    #define _(s)                  wxGetTranslation(_T(s))
+    #define _(s)                     wxGetTranslation(_T(s))
+    #define wxPLURAL(sing, plur, n)  wxGetTranslation(_T(sing), _T(plur), n)
 #endif
 
 // another one which just marks the strings for extraction, but doesn't

locale/Makefile

@@ -16,7 +16,7 @@ XGETTEXT=xgettext
 XARGS=xargs
 
 # common xgettext args: C++ syntax, use the specified macro names as markers
-XGETTEXT_ARGS=-C -k_ -kwxGetTranslation -kwxTRANSLATE -s -j
+XGETTEXT_ARGS=-C -k_ -kwxPLURAL:1,2 -kwxTRANSLATE -s -j
 
 # implicit rules
 %.mo: %.po
@@ -42,7 +42,7 @@ allmo:
 force-update:
 	$(RM) wxstd.po
 
-# print out the percentage of the trsnalted strings
+# print out the percentage of the translated strings
 stats: FORCE
 	@for i in $(WX_LINGUAS); do \
 		x=`$(MSGFMT) -o /dev/null "$$i.po" 2>&1 | sed -e 's/[,\.]//g' \

samples/internat/internat.cpp

@@ -354,7 +354,7 @@ void MyFrame::OnTest2(wxCommandEvent& WXUNUSED(event))
         for (int n = first; n <= last; ++n)
         {
             s << n << _T(" ") <<
-                wxGetTranslation(_T("file deleted"), _T("files deleted"), n) <<
+                wxPLURAL("file deleted", "files deleted", n) <<
                 _T("\n");
         }
         wxMessageBox(s);

samples/internat/readme.txt

@@ -44,14 +44,18 @@ A. First of all, you will need the GNU gettext tools (see the next question).
 
    # generate the .po file for the program itself
    # see `xgettext --help' for options, "-C" is important!
-   xgettext -C -n -k_ -o internat.po ../internat.cpp
+   xgettext -C -n -k_ -kwxPLURAL:1,2 -kwxTRANSLATE -o internat.po ../internat.cpp
    
-   # .po file for wxWindows might be generated in the same way, but for now just
-   # take this one...
-   cp ../wxstd.po .
+   # .po file for wxWindows might be generated in the same way. An already 
+   # generated wxstd.po as well as translations for some languages can be 
+   # found in the locale directory.
+   cp ../../locale/<language>.po ./wxstd.po
+   - or -
+   cp ../../locale/wxstd.po .
 
    # now edit the files and do translate strings (this isn't done by gettext)
-   # you can use another editor if you wish :-)
+   # you can use another editor if you wish :-) No need to edit wxstd.po if you
+   # already got a translated one.
    vi internat.po wxstd.po
 
    # create the message catalog files
@@ -60,7 +64,7 @@ A. First of all, you will need the GNU gettext tools (see the next question).
 
    # run the sample to test it
    cd ..
-   ./internat <language> <langid>
+   ./internat <language> 
 
 Q. How to get the gettext tools?
 A. For Unix, you should be able to get the source distribution of any GNU mirror