locale
--- Internationalization services¶
Source code: Lib/locale.py
Le module locale
donne accès à la base de données et aux fonctionnalités des paramètres linguistiques définis par POSIX. Le mécanisme des paramètres linguistiques de POSIX permet aux développeurs de faire face à certaines problématiques culturelles dans une application, sans avoir à connaître toutes les spécificités de chaque pays où le logiciel est exécuté.
The locale
module is implemented on top of the _locale
module,
which in turn uses an ANSI C locale implementation if available.
Le module locale
définit l'exception et les fonctions suivantes :
- exception locale.Error¶
Exception levée lorsque le paramètre régional passé en paramètre de
setlocale()
n'est pas reconnu.
- locale.setlocale(category, locale=None)¶
Si locale ne vaut pas
None
,setlocale()
modifie le paramètre régional pour la catégorie category. Les catégories disponibles sont listées dans la description des données ci-dessous. locale peut être une chaîne de caractères ou un itérable de deux chaînes de caractères (code de la langue et encodage). Si c'est un itérable, il est converti en un nom de paramètre régional à l'aide du moteur de normalisation fait pour. Si c'est une chaîne vide, les paramètres par défaut de l'utilisateur sont utilisés. Si la modification du paramètre régional échoue, l'exceptionError
est levée. Si elle fonctionne, le nouveau paramètre est renvoyé.Si locale est omis ou vaut
None
, le paramètre actuel de category est renvoyé.setlocale()
n'est pas thread-safe sur la plupart des systèmes. Les applications commencent généralement par un appel deimport locale locale.setlocale(locale.LC_ALL, '')
Cela définit les paramètres régionaux dans toutes les catégories sur ceux par défaut de l'utilisateur (habituellement spécifiés dans la variable d'environnement
LANG
). Si les paramètres régionaux ne sont pas modifiés par la suite, l'utilisation de fils d'exécution ne devrait pas poser de problèmes.
- locale.localeconv()¶
Renvoie la base de données des conventions locales sous forme de dictionnaire. Ce dictionnaire a les chaînes de caractères suivantes comme clés :
Catégorie
Clé
Signification
'decimal_point'
Caractère du séparateur décimal (entre la partie entière et la partie décimale).
'grouping'
Séquence de nombres spécifiant les positions relatives attendues pour
'thousands_sep'
(séparateur de milliers). Si la séquence se termine parCHAR_MAX
, aucun autre regroupement n'est effectué. Si la séquence se termine par un0
, la dernière taille du groupe est utilisée à plusieurs reprises.'thousands_sep'
Caractère utilisé entre les groupes (séparateur de milliers).
'int_curr_symbol'
Symbole monétaire international.
'currency_symbol'
Symbole monétaire local.
'p_cs_precedes/n_cs_precedes'
Si le symbole monétaire précède ou non la valeur (pour les valeurs positives et négatives, respectivement).
'p_sep_by_space/n_sep_by_space'
Si le symbole monétaire est séparé de la valeur par une espace ou non (pour les valeurs positives et négatives, respectivement).
'mon_decimal_point'
Séparateur décimal (entre la partie entière et la partie décimale) utilisé pour les valeurs monétaires.
'frac_digits'
Nombre de décimales utilisées dans le format local des valeurs monétaires.
'int_frac_digits'
Nombre de décimales utilisées dans le format international des valeurs monétaires.
'mon_thousands_sep'
Séparateur de groupe utilisé pour les valeurs monétaires.
'mon_grouping'
Équivalent de
'grouping'
, utilisé pour les valeurs monétaires.'positive_sign'
Symbole utilisé pour indiquer qu'une valeur monétaire est positive.
'negative_sign'
Symbole utilisé pour indiquer qu'une valeur monétaire est négative.
'p_sign_posn/n_sign_posn'
Position du signe (pour les valeurs positives et négatives, respectivement), voir ci-dessous.
Toutes les valeurs numériques peuvent être définies à
CHAR_MAX
pour indiquer qu'il n'y a pas de valeur spécifiée pour ces paramètres régionaux.Les valeurs possibles pour
'p_sign_posn'
et'n_sign_posn'
sont données ci-dessous.Valeur
Explication
0
Le symbole monétaire et la valeur sont entourés de parenthèses.
1
Le signe doit précéder la valeur et le symbole monétaire.
2
Le signe doit suivre la valeur et le symbole monétaire.
3
Le signe doit précéder immédiatement la valeur.
4
Le signe doit suivre immédiatement la valeur.
CHAR_MAX
Rien n'est spécifié dans ces paramètres régionaux.
The function temporarily sets the
LC_CTYPE
locale to theLC_NUMERIC
locale or theLC_MONETARY
locale if locales are different and numeric or monetary strings are non-ASCII. This temporary change affects other threads.Modifié dans la version 3.7: The function now temporarily sets the
LC_CTYPE
locale to theLC_NUMERIC
locale in some cases.
- locale.nl_langinfo(option)¶
Renvoie quelques informations spécifiques aux paramètres régionaux sous forme de chaîne. Cette fonction n'est pas disponible sur tous les systèmes et l'ensemble des options possibles peut également varier d'une plateforme à l'autre. Les valeurs possibles pour les arguments sont des nombres, pour lesquels des constantes symboliques sont disponibles dans le module locale.
La fonction
nl_langinfo()
accepte l'une des clés suivantes. La plupart des descriptions sont extraites des descriptions correspondantes dans la bibliothèque GNU C.- locale.CODESET¶
Récupère une chaîne avec le nom de l'encodage des caractères utilisé par le paramètre régional sélectionné.
- locale.D_T_FMT¶
Récupère une chaîne qui peut être utilisée comme une chaîne de format par
time.strftime()
afin de représenter la date et l'heure pour un paramètre régional spécifique.
- locale.D_FMT¶
Récupère une chaîne qui peut être utilisée comme une chaîne de format par
time.strftime()
afin de représenter une date pour un paramètre régional spécifique.
- locale.T_FMT¶
Récupère une chaîne qui peut être utilisée comme une chaîne de format par
time.strftime()
afin de représenter une heure pour un paramètre régional spécifique.
- locale.T_FMT_AMPM¶
Récupère une chaîne de format pour
time.strftime()
afin de représenter l'heure au format am / pm.
- locale.DAY_1¶
- locale.DAY_2¶
- locale.DAY_3¶
- locale.DAY_4¶
- locale.DAY_5¶
- locale.DAY_6¶
- locale.DAY_7¶
Récupère le nom du n-ième jour de la semaine.
Note
Cela suit la convention américaine qui définit
DAY_1
comme étant dimanche, et non la convention internationale (ISO 8601) où lundi est le premier jour de la semaine.
- locale.ABDAY_1¶
- locale.ABDAY_2¶
- locale.ABDAY_3¶
- locale.ABDAY_4¶
- locale.ABDAY_5¶
- locale.ABDAY_6¶
- locale.ABDAY_7¶
Récupère l'abréviation du n-ième jour de la semaine.
- locale.MON_1¶
- locale.MON_2¶
- locale.MON_3¶
- locale.MON_4¶
- locale.MON_5¶
- locale.MON_6¶
- locale.MON_7¶
- locale.MON_8¶
- locale.MON_9¶
- locale.MON_10¶
- locale.MON_11¶
- locale.MON_12¶
Récupère le nom du n-ième mois.
- locale.ABMON_1¶
- locale.ABMON_2¶
- locale.ABMON_3¶
- locale.ABMON_4¶
- locale.ABMON_5¶
- locale.ABMON_6¶
- locale.ABMON_7¶
- locale.ABMON_8¶
- locale.ABMON_9¶
- locale.ABMON_10¶
- locale.ABMON_11¶
- locale.ABMON_12¶
Récupère l'abréviation du n-ième mois.
- locale.RADIXCHAR¶
Récupère le caractère de séparation radix (point décimal, virgule décimale, etc.).
- locale.THOUSEP¶
Récupère le caractère de séparation des milliers (groupes de 3 chiffres).
- locale.YESEXPR¶
Récupère une expression régulière qui peut être utilisée par la fonction regex pour reconnaître une réponse positive à une question fermée (oui / non).
- locale.NOEXPR¶
Get a regular expression that can be used with the
regex(3)
function to recognize a negative response to a yes/no question.
- locale.CRNCYSTR¶
Récupère le symbole monétaire, précédé de « - » si le symbole doit apparaître avant la valeur, « + » s'il doit apparaître après la valeur, ou « . » s'il doit remplacer le caractère de séparation radix.
- locale.ERA¶
Récupère une chaîne qui représente l'ère utilisée pour le paramètre régional actuel.
La plupart des paramètres régionaux ne définissent pas cette valeur. Un exemple de région qui définit bien cette valeur est le japonais. Au Japon, la représentation traditionnelle des dates comprend le nom de l'ère correspondant au règne de l'empereur de l'époque.
Normalement, il ne devrait pas être nécessaire d'utiliser cette valeur directement. Spécifier le modificateur
E
dans leurs chaînes de format provoque l'utilisation de cette information par la fonctiontime.strftime()
. Le format de la chaîne renvoyée n'est pas spécifié, et vous ne devez donc pas supposer en avoir connaissance sur des systèmes différents.
- locale.ERA_D_T_FMT¶
Récupère la chaîne de format pour
time.strftime()
afin de représenter la date et l'heure pour un paramètre régional spécifique basée sur une ère.
- locale.ERA_D_FMT¶
Récupère la chaîne de format pour
time.strftime()
afin de représenter une date pour un paramètre régional spécifique basée sur une ère.
- locale.ERA_T_FMT¶
Récupère la chaîne de format pour
time.strftime()
afin de représenter une heure pour un paramètre régional spécifique basée sur une ère.
- locale.ALT_DIGITS¶
Récupère une représentation de 100 valeurs maximum utilisées pour représenter les valeurs de 0 à 99.
The function temporarily sets the
LC_CTYPE
locale to the locale of the category that determines the requested value (LC_TIME
,LC_NUMERIC
,LC_MONETARY
orLC_MESSAGES
) if locales are different and the resulting string is non-ASCII. This temporary change affects other threads.Modifié dans la version 3.14: The function now temporarily sets the
LC_CTYPE
locale in some cases.
- locale.getdefaultlocale([envvars])¶
Tente de déterminer les paramètres régionaux par défaut, puis les renvoie sous la forme d'un n-uplet
(code de la langue, encodage)
.D'après POSIX, un programme qui n'a pas appelé
setlocale(LC_ALL, '')
fonctionne en utilisant le paramètre régional portable'C'
. Appelersetlocale(LC_ALL, '')
lui permet d'utiliser les paramètres régionaux par défaut définis par la variableLANG
. Comme nous ne voulons pas interférer avec les paramètres régionaux actuels, nous émulons donc le comportement décrit ci-dessus.Afin de maintenir la compatibilité avec d'autres plateformes, non seulement la variable
LANG
est testée, mais c'est aussi le cas pour toute une liste de variables passés en paramètre via envvars. La première variable à être définie sera utilisée. envvars utilise par défaut le chemin de recherche utilisé dans GNU gettext ; il doit toujours contenir le nom de variable'LANG'
. Le chemin de recherche de GNU gettext contient'LC_ALL'
,'LC_CTYPE'
,'LANG'
et'LANGUAGE'
, dans cet ordre.À l'exception du code
'C'
, le code d'une langue correspond à la RFC 1766. Le code de la langue et l'encodage peuvent valoirNone
si leur valeur ne peut être déterminée.Deprecated since version 3.11, will be removed in version 3.15.
- locale.getlocale(category=LC_CTYPE)¶
Returns the current setting for the given locale category as sequence containing language code, encoding. category may be one of the
LC_*
values exceptLC_ALL
. It defaults toLC_CTYPE
.À l'exception du code
'C'
, le code d'une langue correspond à la RFC 1766. Le code de la langue et l'encodage peuvent valoirNone
si leur valeur ne peut être déterminée.
- locale.getpreferredencoding(do_setlocale=True)¶
Return the locale encoding used for text data, according to user preferences. User preferences are expressed differently on different systems, and might not be available programmatically on some systems, so this function only returns a guess.
Sur certains systèmes, il est nécessaire d'invoquer
setlocale()
pour obtenir les préférences de l'utilisateur, cette fonction n'est donc pas utilisable sans protection dans les programmes à fils d'exécutions multiples. Si l'appel desetlocale
n'est pas nécessaire ou souhaité, do_setlocale doit être réglé àFalse
.On Android or if the Python UTF-8 Mode is enabled, always return
'utf-8'
, the locale encoding and the do_setlocale argument are ignored.The Python preinitialization configures the LC_CTYPE locale. See also the filesystem encoding and error handler.
Modifié dans la version 3.7: The function now always returns
"utf-8"
on Android or if the Python UTF-8 Mode is enabled.
- locale.getencoding()¶
Get the current locale encoding:
On Android and VxWorks, return
"utf-8"
.On Unix, return the encoding of the current
LC_CTYPE
locale. Return"utf-8"
ifnl_langinfo(CODESET)
returns an empty string: for example, if the current LC_CTYPE locale is not supported.On Windows, return the ANSI code page.
The Python preinitialization configures the LC_CTYPE locale. See also the filesystem encoding and error handler.
This function is similar to
getpreferredencoding(False)
except this function ignores the Python UTF-8 Mode.Ajouté dans la version 3.11.
- locale.normalize(localename)¶
Renvoie un code normalisé pour le nom du paramètre régional fourni. Ce code renvoyé est structuré de façon à être utilisé avec
setlocale()
. Si la normalisation échoue, le nom d'origine est renvoyé inchangé.Si l'encodage donné n'est pas connu, la fonction utilise l'encodage par défaut pour le code du paramètre régional, tout comme
setlocale()
.
- locale.strcoll(string1, string2)¶
Compare deux chaînes en se basant sur le paramètre
LC_COLLATE
actuel. Comme toute autre fonction de comparaison, renvoie une valeur négative, positive, ou0
, selon si string1 est lexicographiquement inférieure, supérieure, ou égale à string2.
- locale.strxfrm(string)¶
Transforme une chaîne de caractères en une chaîne qui peut être utilisée dans les comparaisons sensibles aux paramètres régionaux. Par exemple,
strxfrm(s1) < strxfrm(s2)
est équivalent àstrcoll(s1, s2) < 0
. Cette fonction peut être utilisée lorsque la même chaîne est comparée de façon répétitive, par exemple lors de l'assemblage d'une séquence de chaînes.
- locale.format_string(format, val, grouping=False, monetary=False)¶
Formats a number val according to the current
LC_NUMERIC
setting. The format follows the conventions of the%
operator. For floating-point values, the decimal point is modified if appropriate. If grouping isTrue
, also takes the grouping into account.Si monetary est vrai, la conversion utilise un séparateur des milliers monétaire et des chaînes de regroupement.
Traite les marqueurs de structure en
format % val
, mais en prenant en compte les paramètres régionaux actuels.Modifié dans la version 3.7: The monetary keyword parameter was added.
- locale.currency(val, symbol=True, grouping=False, international=False)¶
Structure un nombre val en fonction du paramètre
LC_MONETARY
actuel.The returned string includes the currency symbol if symbol is true, which is the default. If grouping is
True
(which is not the default), grouping is done with the value. If international isTrue
(which is not the default), the international currency symbol is used.Note
This function will not work with the 'C' locale, so you have to set a locale via
setlocale()
first.
- locale.str(float)¶
Formats a floating-point number using the same format as the built-in function
str(float)
, but takes the decimal point into account.
- locale.delocalize(string)¶
Convertit une chaîne de caractères en une chaîne de nombres normalisés, en suivant les réglages
LC_NUMERIC
.Ajouté dans la version 3.5.
- locale.localize(string, grouping=False, monetary=False)¶
Converts a normalized number string into a formatted string following the
LC_NUMERIC
settings.Ajouté dans la version 3.10.
- locale.atof(string, func=float)¶
Converts a string to a number, following the
LC_NUMERIC
settings, by calling func on the result of callingdelocalize()
on string.
- locale.atoi(string)¶
Convertit une chaîne de caractères en un entier, en suivant les réglages
LC_NUMERIC
.
- locale.LC_CTYPE¶
Locale category for the character type functions. Most importantly, this category defines the text encoding, i.e. how bytes are interpreted as Unicode codepoints. See PEP 538 and PEP 540 for how this variable might be automatically coerced to
C.UTF-8
to avoid issues created by invalid settings in containers or incompatible settings passed over remote SSH connections.Python doesn't internally use locale-dependent character transformation functions from
ctype.h
. Instead, an internalpyctype.h
provides locale-independent equivalents likePy_TOLOWER
.
- locale.LC_COLLATE¶
Catégorie de paramètre régional pour les tris de chaînes de caractères. Les fonctions
strcoll()
etstrxfrm()
du modulelocale
sont concernées.
- locale.LC_TIME¶
Catégorie de paramètre régional pour la mise en forme de la date et de l'heure. La fonction
time.strftime()
suit ces conventions.
- locale.LC_MONETARY¶
Catégorie de paramètre régional pour la mise en forme des valeurs monétaires. Les options disponibles sont accessibles à partir de la fonction
localeconv()
.
- locale.LC_MESSAGES¶
Catégorie de paramètre régional pour l'affichage de messages. Actuellement, Python ne gère pas les messages spécifiques aux applications qui sont sensibles aux paramètres régionaux. Les messages affichés par le système d'exploitation, comme ceux renvoyés par
os.strerror()
peuvent être affectés par cette catégorie.This value may not be available on operating systems not conforming to the POSIX standard, most notably Windows.
- locale.LC_NUMERIC¶
Locale category for formatting numbers. The functions
format_string()
,atoi()
,atof()
andstr()
of thelocale
module are affected by that category. All other numeric formatting operations are not affected.
- locale.LC_ALL¶
Combinaison de tous les paramètres régionaux. Si cette option est utilisée lors du changement de paramètres régionaux, la définition de ces paramètres pour toutes les catégories est tentée. Si cela échoue pour n'importe quelle catégorie, aucune d'entre elles n'est modifiée. Lorsque les paramètres régionaux sont récupérés à l'aide de cette option, une chaîne de caractères indiquant le réglage pour toutes les catégories est renvoyée. Cette chaîne peut alors être utilisée plus tard pour restaurer les paramètres d'origine.
- locale.CHAR_MAX¶
Ceci est une constante symbolique utilisée pour différentes valeurs renvoyées par
localeconv()
.
Exemple :
>>> import locale
>>> loc = locale.getlocale() # get current locale
# use German locale; name might vary with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale
Contexte, détails, conseils, astuces et mises en garde¶
The C standard defines the locale as a program-wide property that may be relatively expensive to change. On top of that, some implementations are broken in such a way that frequent locale changes may cause core dumps. This makes the locale somewhat painful to use correctly.
Initialement, lorsqu'un programme est démarré, les paramètres régionaux C
sont utilisés, peu importe les réglages de l'utilisateur. Il y a toutefois une exception : la catégorie LC_CTYPE
est modifiée au démarrage pour définir l'encodage des paramètres régionaux actuels comme celui défini par l'utilisateur. Le programme doit explicitement dire qu'il veut utiliser les réglages de l'utilisateur pour les autres catégories, en appelant setlocale(LC_ALL, '')
.
C'est généralement une mauvaise idée d'appeler setlocale()
dans une routine de bibliothèque car cela a pour effet secondaire d'affecter le programme entier. Sauvegarder et restaurer les paramètres est presque aussi mauvais : c'est coûteux et cela affecte d'autres fils d'exécutions qui s'exécutent avant que les paramètres n'aient été restaurés.
Si, lors du développement d'un module à usage général, vous avez besoin d'une version indépendante des paramètres régionaux pour une opération y étant sensible (comme c'est le cas pour certains formats utilisés avec time.strftime()
), vous devez trouver un moyen de le faire sans utiliser la routine de la bibliothèque standard. Le mieux est encore de se convaincre que l'usage des paramètres régionaux est une bonne chose. Ce n'est qu'en dernier recours que vous devez documenter que votre module n'est pas compatible avec les réglages du paramètre régional C
.
The only way to perform numeric operations according to the locale is to use the
special functions defined by this module: atof()
, atoi()
,
format_string()
, str()
.
Il n'y a aucun moyen d'effectuer des conversions de casse et des classifications de caractères en fonction des paramètres régionaux. Pour les chaînes de caractères (Unicode), celles-ci se font uniquement en fonction de la valeur du caractère, tandis que pour les chaînes d'octets, les conversions et les classifications se font en fonction de la valeur ASCII de l'octet, et les octets dont le bit de poids fort est à 1 (c'est-à-dire les octets non ASCII) ne sont jamais convertis ou considérés comme faisant partie d'une classe de caractères comme une lettre ou une espace.
Pour les auteurs d'extensions et les programmes qui intègrent Python¶
Les modules d'extensions ne devraient jamais appeler setlocale()
, sauf pour connaître le paramètre régional actuel. Mais comme la valeur renvoyée ne peut être utilisée que pour le restaurer, ce n'est pas très utile (sauf peut-être pour savoir si le paramètre régional est défini à C
ou non).
When Python code uses the locale
module to change the locale, this also
affects the embedding application. If the embedding application doesn't want
this to happen, it should remove the _locale
extension module (which does
all the work) from the table of built-in modules in the config.c
file,
and make sure that the _locale
module is not accessible as a shared
library.
Accéder aux catalogues de messages¶
- locale.gettext(msg)¶
- locale.dgettext(domain, msg)¶
- locale.dcgettext(domain, msg, category)¶
- locale.textdomain(domain)¶
- locale.bindtextdomain(domain, dir)¶
- locale.bind_textdomain_codeset(domain, codeset)¶
The locale module exposes the C library's gettext interface on systems that
provide this interface. It consists of the functions gettext()
,
dgettext()
, dcgettext()
, textdomain()
, bindtextdomain()
,
and bind_textdomain_codeset()
. These are similar to the same functions in
the 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 functions, and
should use gettext
instead. A known exception to this rule are
applications that link with additional C libraries which internally invoke
C functions gettext
or dcgettext
. For these applications, it may be
necessary to bind the text domain, so that the libraries can properly locate
their message catalogs.