mingw/gettext/gettext-tools/doc/lang-python.texi

@c This file is part of the GNU gettext manual.
@c Copyright (C) 1995-2020 Free Software Foundation, Inc.
@c See the file gettext.texi for copying conditions.

@node Python
@subsection Python
@cindex Python

@table @asis
@item RPMs
python

@item Ubuntu packages
python

@item File extension
@code{py}

@item String syntax
@code{'abc'}, @code{u'abc'}, @code{r'abc'}, @code{ur'abc'},
@*@code{"abc"}, @code{u"abc"}, @code{r"abc"}, @code{ur"abc"},
@*@code{'''abc'''}, @code{u'''abc'''}, @code{r'''abc'''}, @code{ur'''abc'''},
@*@code{"""abc"""}, @code{u"""abc"""}, @code{r"""abc"""}, @code{ur"""abc"""}

@item gettext shorthand
@code{_('abc')} etc.

@item gettext/ngettext functions
@code{gettext.gettext}, @code{gettext.dgettext},
@code{gettext.ngettext}, @code{gettext.dngettext},
also @code{ugettext}, @code{ungettext}

@item textdomain
@code{gettext.textdomain} function, or
@code{gettext.install(@var{domain})} function

@item bindtextdomain
@code{gettext.bindtextdomain} function, or
@code{gettext.install(@var{domain},@var{localedir})} function

@item setlocale
not used by the gettext emulation

@item Prerequisite
@code{import gettext}

@item Use or emulate GNU gettext
emulate

@item Extractor
@code{xgettext}

@item Formatting with positions
@code{'...%(ident)d...' % @{ 'ident': value @}}

@item Portability
fully portable

@item po-mode marking
---
@end table

An example is available in the @file{examples} directory: @code{hello-python}.

A note about format strings: Python supports format strings with unnamed
arguments, such as @code{'...%d...'}, and format strings with named arguments,
such as @code{'...%(ident)d...'}.  The latter are preferable for
internationalized programs, for two reasons:

@itemize @bullet
@item
When a format string takes more than one argument, the translator can provide
a translation that uses the arguments in a different order, if the format
string uses named arguments.  For example, the translator can reformulate
@smallexample
"'%(volume)s' has only %(freespace)d bytes free."
@end smallexample
@noindent
to
@smallexample
"Only %(freespace)d bytes free on '%(volume)s'."
@end smallexample
@noindent
Additionally, the identifiers also provide some context to the translator.

@item
In the context of plural forms, the format string used for the singular form
does not use the numeric argument in many languages.  Even in English, one
prefers to write @code{"one hour"} instead of @code{"1 hour"}.  Omitting
individual arguments from format strings like this is only possible with
the named argument syntax.  (With unnamed arguments, Python -- unlike C --
verifies that the format string uses all supplied arguments.)
@end itemize