@c This file is part of the GNU gettext manual.
@c Copyright (C) 1995-2025 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 @}}
@*@code{'...@{ident@}...'.format(ident=value)}
@*@code{'...@{0@}...@{1@}...'.format(value0,value1)}
@*@code{'...@{@}...@{@}...'.format(value0,value1)}

@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

A note about f-strings (PEP 498): @code{xgettext}
@itemize @bullet
@item
syntactically recognizes f-strings,
@item
is able to extract f-strings that contain no sub-expressions.
@end itemize
@noindent
However, @code{xgettext} does not extract f-strings marked for translation
that contain sub-expressions.  This will not work as expected:
@smallexample
_(f"The file @{file[i]@} does not exist.")
@end smallexample
@noindent
because the translator is generally not a programmer and should thus not be
confronted with expressions from the programming language.

@subheading Related software

An internationalization system based on GNU gettext and PO files is
@url{https://babel.pocoo.org/, Babel}.
