[Python-checkins] python/dist/src/Doc/lib libgettext.tex, 1.24,
1.25 liblocale.tex, 1.36, 1.37
niemeyer at users.sourceforge.net
niemeyer at users.sourceforge.net
Thu Jul 22 20:44:02 CEST 2004
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv3065/Doc/lib
Modified Files:
libgettext.tex liblocale.tex
Log Message:
This change implements the following gettext features, as
discussed recently in python-dev:
In _locale module:
- bind_textdomain_codeset() binding
In gettext module:
- bind_textdomain_codeset() function
- lgettext(), lngettext(), ldgettext(), ldngettext(),
which return translated strings encoded in
preferred system encoding, if
bind_textdomain_codeset() was not used.
- Added equivalent functionality in translate()
function and catalog classes.
Every change was also documented.
Index: libgettext.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libgettext.tex,v
retrieving revision 1.24
retrieving revision 1.25
diff -C2 -d -r1.24 -r1.25
*** libgettext.tex 10 Jul 2004 16:01:10 -0000 1.24
--- libgettext.tex 22 Jul 2004 18:43:59 -0000 1.25
***************
*** 52,55 ****
--- 52,63 ----
\end{funcdesc}
+ \begin{funcdesc}{bind_textdomain_codeset}{domain\optional{, codeset}}
+ Bind the \var{domain} to \var{codeset}, changing the encoding of
+ strings returned by the \function{gettext()} family of functions.
+ If \var{codeset} is omitted, then the current binding is returned.
+
+ \versionadded{2.4}
+ \end{funcdesc}
+
\begin{funcdesc}{textdomain}{\optional{domain}}
Change or query the current global domain. If \var{domain} is
***************
*** 65,68 ****
--- 73,84 ----
\end{funcdesc}
+ \begin{funcdesc}{lgettext}{message}
+ Equivalent to \function{gettext()}, but the translation is returned
+ in the preferred system encoding, if no other encoding was explicitly
+ set with \function{bind_textdomain_codeset()}.
+
+ \versionadded{2.4}
+ \end{funcdesc}
+
\begin{funcdesc}{dgettext}{domain, message}
Like \function{gettext()}, but look the message up in the specified
***************
*** 70,73 ****
--- 86,97 ----
\end{funcdesc}
+ \begin{funcdesc}{ldgettext}{domain, message}
+ Equivalent to \function{dgettext()}, but the translation is returned
+ in the preferred system encoding, if no other encoding was explicitly
+ set with \function{bind_textdomain_codeset()}.
+
+ \versionadded{2.4}
+ \end{funcdesc}
+
\begin{funcdesc}{ngettext}{singular, plural, n}
***************
*** 88,91 ****
--- 112,123 ----
\end{funcdesc}
+ \begin{funcdesc}{lngettext}{singular, plural, n}
+ Equivalent to \function{ngettext()}, but the translation is returned
+ in the preferred system encoding, if no other encoding was explicitly
+ set with \function{bind_textdomain_codeset()}.
+
+ \versionadded{2.4}
+ \end{funcdesc}
+
\begin{funcdesc}{dngettext}{domain, singular, plural, n}
Like \function{ngettext()}, but look the message up in the specified
***************
*** 95,98 ****
--- 127,139 ----
\end{funcdesc}
+ \begin{funcdesc}{ldngettext}{domain, singular, plural, n}
+ Equivalent to \function{dngettext()}, but the translation is returned
+ in the preferred system encoding, if no other encoding was explicitly
+ set with \function{bind_textdomain_codeset()}.
+
+ \versionadded{2.4}
+ \end{funcdesc}
+
+
Note that GNU \program{gettext} also defines a \function{dcgettext()}
***************
*** 153,158 ****
\begin{funcdesc}{translation}{domain\optional{, localedir\optional{,
! languages\optional{,
! class_,\optional{fallback}}}}}
Return a \class{Translations} instance based on the \var{domain},
\var{localedir}, and \var{languages}, which are first passed to
--- 194,199 ----
\begin{funcdesc}{translation}{domain\optional{, localedir\optional{,
! languages\optional{, class_\optional{,
! fallback\optional{, codeset}}}}}}
Return a \class{Translations} instance based on the \var{domain},
\var{localedir}, and \var{languages}, which are first passed to
***************
*** 162,166 ****
is either \var{class_} if provided, otherwise
\class{GNUTranslations}. The class's constructor must take a single
! file object argument.
If multiple files are found, later files are used as fallbacks for
--- 203,208 ----
is either \var{class_} if provided, otherwise
\class{GNUTranslations}. The class's constructor must take a single
! file object argument. If provided, \var{codeset} will change the
! charset used to encode translated strings.
If multiple files are found, later files are used as fallbacks for
***************
*** 173,183 ****
and returns a \class{NullTranslations} instance if \var{fallback} is
true.
\end{funcdesc}
! \begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode}}}
This installs the function \function{_} in Python's builtin namespace,
! based on \var{domain}, and \var{localedir} which are passed to the
! function \function{translation()}. The \var{unicode} flag is passed to
! the resulting translation object's \method{install} method.
As seen below, you usually mark the strings in your application that are
--- 215,229 ----
and returns a \class{NullTranslations} instance if \var{fallback} is
true.
+
+ \versionchanged[Added the \var{codeset} parameter]{2.4}
\end{funcdesc}
! \begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode
! \optional{, codeset}}}}
This installs the function \function{_} in Python's builtin namespace,
! based on \var{domain}, \var{localedir}, and \var{codeset} which are
! passed to the function \function{translation()}. The \var{unicode}
! flag is passed to the resulting translation object's \method{install}
! method.
As seen below, you usually mark the strings in your application that are
***************
*** 192,195 ****
--- 238,243 ----
Python's builtin namespace, so it is easily accessible in all modules
of your application.
+
+ \versionchanged[Added the \var{codeset} parameter]{2.4}
\end{funcdesc}
***************
*** 224,233 ****
\begin{methoddesc}[NullTranslations]{gettext}{message}
! If a fallback has been set, forward \method{gettext} to the fallback.
Otherwise, return the translated message. Overridden in derived classes.
\end{methoddesc}
\begin{methoddesc}[NullTranslations]{ugettext}{message}
! If a fallback has been set, forward \method{ugettext} to the fallback.
Otherwise, return the translated message as a Unicode string.
Overridden in derived classes.
--- 272,288 ----
\begin{methoddesc}[NullTranslations]{gettext}{message}
! If a fallback has been set, forward \method{gettext()} to the fallback.
! Otherwise, return the translated message. Overridden in derived classes.
! \end{methoddesc}
!
! \begin{methoddesc}[NullTranslations]{lgettext}{message}
! If a fallback has been set, forward \method{lgettext()} to the fallback.
Otherwise, return the translated message. Overridden in derived classes.
+
+ \versionadded{2.4}
\end{methoddesc}
\begin{methoddesc}[NullTranslations]{ugettext}{message}
! If a fallback has been set, forward \method{ugettext()} to the fallback.
Otherwise, return the translated message as a Unicode string.
Overridden in derived classes.
***************
*** 235,239 ****
\begin{methoddesc}[NullTranslations]{ngettext}{singular, plural, n}
! If a fallback has been set, forward \method{ngettext} to the fallback.
Otherwise, return the translated message. Overridden in derived classes.
--- 290,294 ----
\begin{methoddesc}[NullTranslations]{ngettext}{singular, plural, n}
! If a fallback has been set, forward \method{ngettext()} to the fallback.
Otherwise, return the translated message. Overridden in derived classes.
***************
*** 241,246 ****
\end{methoddesc}
\begin{methoddesc}[NullTranslations]{ungettext}{singular, plural, n}
! If a fallback has been set, forward \method{ungettext} to the fallback.
Otherwise, return the translated message as a Unicode string.
Overridden in derived classes.
--- 296,308 ----
\end{methoddesc}
+ \begin{methoddesc}[NullTranslations]{lngettext}{singular, plural, n}
+ If a fallback has been set, forward \method{ngettext()} to the fallback.
+ Otherwise, return the translated message. Overridden in derived classes.
+
+ \versionadded{2.4}
+ \end{methoddesc}
+
\begin{methoddesc}[NullTranslations]{ungettext}{singular, plural, n}
! If a fallback has been set, forward \method{ungettext()} to the fallback.
Otherwise, return the translated message as a Unicode string.
Overridden in derived classes.
***************
*** 257,260 ****
--- 319,336 ----
\end{methoddesc}
+ \begin{methoddesc}[NullTranslations]{output_charset}{}
+ Return the ``protected'' \member{_output_charset} variable, which
+ defines the encoding used to return translated messages.
+
+ \versionadded{2.4}
+ \end{methoddesc}
+
+ \begin{methoddesc}[NullTranslations]{set_output_charset}{charset}
+ Change the ``protected'' \member{_output_charset} variable, which
+ defines the encoding used to return translated messages.
+
+ \versionadded{2.4}
+ \end{methoddesc}
+
\begin{methoddesc}[NullTranslations]{install}{\optional{unicode}}
If the \var{unicode} flag is false, this method installs
***************
*** 324,327 ****
--- 400,411 ----
\end{methoddesc}
+ \begin{methoddesc}[GNUTranslations]{lgettext}{message}
+ Equivalent to \method{gettext()}, but the translation is returned
+ in the preferred system encoding, if no other encoding was explicitly
+ set with \method{set_output_charset()}.
+
+ \versionadded{2.4}
+ \end{methoddesc}
+
\begin{methoddesc}[GNUTranslations]{ugettext}{message}
Look up the \var{message} id in the catalog and return the
***************
*** 347,350 ****
--- 431,442 ----
\end{methoddesc}
+ \begin{methoddesc}[GNUTranslations]{lngettext}{singular, plural, n}
+ Equivalent to \method{gettext()}, but the translation is returned
+ in the preferred system encoding, if no other encoding was explicitly
+ set with \method{set_output_charset()}.
+
+ \versionadded{2.4}
+ \end{methoddesc}
+
\begin{methoddesc}[GNUTranslations]{ungettext}{singular, plural, n}
Do a plural-forms lookup of a message id. \var{singular} is used as
***************
*** 496,500 ****
import gettext
t = gettext.translation('spam', '/usr/share/locale')
! _ = t.gettext
\end{verbatim}
--- 588,592 ----
import gettext
t = gettext.translation('spam', '/usr/share/locale')
! _ = t.lgettext
\end{verbatim}
***************
*** 634,637 ****
--- 726,744 ----
use of command line switches.
+ \subsubsection{\function{gettext()} vs. \function{lgettext()}}
+ In Python 2.4 the \function{lgettext()} family of functions were
+ introduced. The intention of these functions is to provide an
+ alternative which is more compliant with the current
+ implementation of GNU gettext. Unlike \function{gettext()}, which
+ returns strings encoded with the same codeset used in the
+ translation file, \function{lgettext()} will return strings
+ encoded with the preferred system encoding, as returned by
+ \function{locale.getpreferredencoding()}. Also notice that
+ Python 2.4 introduces new functions to explicitly choose
+ the codeset used in translated strings. If a codeset is explicitly
+ set, even \function{lgettext()} will return translated strings in
+ the requested codeset, as would be expected in the GNU gettext
+ implementation.
+
\subsection{Acknowledgements}
***************
*** 648,650 ****
--- 755,758 ----
\item Fran\c cois Pinard
\item Barry Warsaw
+ \item Gustavo Niemeyer
\end{itemize}
Index: liblocale.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/liblocale.tex,v
retrieving revision 1.36
retrieving revision 1.37
diff -C2 -d -r1.36 -r1.37
*** liblocale.tex 8 Jun 2004 18:52:41 -0000 1.36
--- liblocale.tex 22 Jul 2004 18:43:59 -0000 1.37
***************
*** 470,477 ****
that provide this interface. It consists of the functions
\function{gettext()}, \function{dgettext()}, \function{dcgettext()},
! \function{textdomain()}, and \function{bindtextdomain()}. These are
! similar to the same functions in the \refmodule{gettext} module, but use
! the C library's binary format for message catalogs, and the C
! library's search algorithms for locating message catalogs.
Python applications should normally find no need to invoke these
--- 470,478 ----
that provide this interface. It consists of the functions
\function{gettext()}, \function{dgettext()}, \function{dcgettext()},
! \function{textdomain()}, \function{bindtextdomain()}, and
! \function{bind_textdomain_codeset()}. These are similar to the same
! functions in the \refmodule{gettext} module, but use the C library's
! binary format for message catalogs, and the C library's search
! algorithms for locating message catalogs.
Python applications should normally find no need to invoke these
***************
*** 479,483 ****
exception to this rule are applications that link use additional C
libraries which internally invoke \cfunction{gettext()} or
! \function{cdgettext()}. For these applications, it may be necessary to
bind the text domain, so that the libraries can properly locate their
message catalogs.
--- 480,484 ----
exception to this rule are applications that link use additional C
libraries which internally invoke \cfunction{gettext()} or
! \function{dcgettext()}. For these applications, it may be necessary to
bind the text domain, so that the libraries can properly locate their
message catalogs.
More information about the Python-checkins
mailing list