locale — Services d'internationalisation

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é.

Le module locale est implémenté au-dessus du module _locale, qui lui-même utilise l'implémentation du paramètre régional ANSI C si disponible.

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'exception Error 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 de :

import 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
LC_NUMERIC	'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 par CHAR_MAX, aucun autre regroupement n'est effectué. Si la séquence se termine par un 0, la dernière taille du groupe est utilisée à plusieurs reprises.
	'thousands_sep'	Caractère utilisé entre les groupes (séparateur de milliers).
LC_MONETARY	'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 sets temporarily the LC_CTYPE locale to the LC_NUMERIC locale or the LC_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: La fonction définit maintenant la valeur du paramètre LC_CTYPE à celle du paramètre LC_NUMERIC temporairement dans certains cas.

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.

DAY_1 ... 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.

ABDAY_1 ... ABDAY_7

Récupère l'abréviation du n-ième jour de la semaine.

MON_1 ... MON_12

Récupère le nom du n-ième mois.

ABMON_1 ... 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).

Note

L'expression est dans une syntaxe adaptée à la fonction regex() de la bibliothèque C, qui peut différer de la syntaxe utilisée par re.

locale.NOEXPR

Récupère une expression régulière qui peut être utilisée par la fonction regex(3) pour reconnaître une réponse négative à une question fermée (oui / non).

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 fonction time.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.

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'. Appeler setlocale(LC_ALL, '') lui permet d'utiliser les paramètres régionaux par défaut définis par la variable LANG. 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 valoir None si leur valeur ne peut être déterminée.

locale.getlocale(category=LC_CTYPE)

Renvoie les réglages actuels pour la catégorie de paramètres régionaux donnée, sous la forme d'une séquence contenant le code de la langue et l'encodage. La catégorie category peut être l'une des valeurs LC_* à l'exception de LC_ALL. La valeur par défaut est LC_CTYPE.

À l'exception du code 'C', le code d'une langue correspond à la RFC 1766. Le code de la langue et l'encodage peuvent valoir None si leur valeur ne peut être déterminée.

locale.getpreferredencoding(do_setlocale=True)

Renvoie le codage utilisé pour les données textuelles, selon les préférences de l'utilisateur. Les préférences de l'utilisateur sont exprimées différemment selon les systèmes et peuvent ne pas être disponibles via les interfaces de programmation sur certains systèmes. Cette fonction ne renvoie donc qu'une supposition.

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 de setlocale n'est pas nécessaire ou souhaité, do_setlocale doit être réglé à False.

Sur Android ou dans le mode UTF-8 (avec l'option -X utf8), renvoie toujours 'UTF-8', la locale et l'argument do_setlocale sont ignorés.

Modifié dans la version 3.7: La fonction renvoie maintenant toujours UTF-8 sur Android ou si le mode UTF-8 est activé.

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.resetlocale(category=LC_ALL)

Définit le paramètre régional de la catégorie category au réglage par défaut.

Le réglage par défaut est déterminé en appelant getdefaultlocale(). La catégorie category vaut par défaut LC_ALL.

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, ou 0, 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)

Structure un nombre val en fonction du paramètre LC_NUMERIC actuel. Le format suit les conventions de l'opérateur %. Pour les valeurs à virgule flottante, le point décimal est modifié si nécessaire. Si grouping est vrai, le regroupement est également pris en compte.

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.format(format, val, grouping=False, monetary=False)

Please note that this function works like format_string() but will only work for exactly one %char specifier. For example, '%f' and '%.0f' are both valid specifiers, but '%f KiB' is not.

For whole format strings, use format_string().

Obsolète depuis la version 3.7: Use format_string() instead.

locale.currency(val, symbol=True, grouping=False, international=False)

Structure un nombre val en fonction du paramètre LC_MONETARY actuel.

La chaîne renvoyée inclut le symbole monétaire si symbol est vrai, ce qui est le cas par défaut. Si grouping est vrai (ce qui n'est pas le cas par défaut), un regroupement est effectué avec la valeur. Si international est vrai (ce qui n'est pas le cas par défaut), le symbole de la devise internationale est utilisé.

Notez que cette fonction ne fonctionnera pas avec le paramètre régional 'C', vous devez donc d'abord en définir un via setlocale().

locale.str(float)

Structure un nombre flottant en utilisant le même format que la fonction native str(float), mais en prenant en compte le point décimal.

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.

Nouveau dans la version 3.5.

locale.atof(string)

Convertit une chaîne de caractères en nombre à virgule flottante, en suivant les réglages LC_NUMERIC.

locale.atoi(string)

Convertit une chaîne de caractères en un entier, en suivant les réglages LC_NUMERIC.

locale.LC_CTYPE

Catégorie de paramètre régional pour les fonctions de type caractère. Suivant les réglages de la catégorie, les fonctions du module string gérant la casse peuvent changer leur comportement.

locale.LC_COLLATE

Catégorie de paramètre régional pour les tris de chaînes de caractères. Les fonctions strcoll() et strxfrm() du module locale 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.

locale.LC_NUMERIC

Catégorie de paramètre régional pour la mise en forme des nombres. Les fonctions format(), atoi(), atof() et str() du module locale sont affectées par cette catégorie. Toutes les autres opérations de mise en forme des nombres ne sont pas affectées.

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

La norme C définie les paramètres régionaux comme une propriété à l'échelle d'un programme, qui peut être relativement coûteuse à changer. En plus de cela, certaines implémentations ne fonctionnent pas car des changements fréquents de paramètres régionaux peuvent causer des core dumps. Cela rend l'utilisation correcte de ces paramètres quelque peu pénible.

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.

La seule façon d'effectuer des opérations numériques conformément aux paramètres régionaux est d'utiliser les fonctions spéciales définies par ce module : atof(), atoi(), format(), 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).

Lorsque le code Python utilise le module locale pour changer le paramètre régional, cela affecte également l'application intégrée. Si l'application intégrée ne souhaite pas que cela se produise, elle doit supprimer le module d'extension _locale (qui fait tout le travail) de la table des modules natifs se trouvant dans le fichier config.c, et s'assurer que le module _locale n'est pas accessible en tant que bibliothèque partagée.

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)

Le module locale expose l'interface gettext de la bibliothèque C sur les systèmes qui fournissent cette interface. Il se compose des fonctions gettext(), dgettext(), dcgettext(), textdomain(), bindtextdomain() et bind_textdomain_codeset(). Elles sont similaires aux fonctions du module gettext, mais utilisent le format binaire de la bibliothèque C pour les catalogues de messages.

Les applications Python ne devraient normalement pas avoir besoin de faire appel à ces fonctions, mais devraient plutôt utiliser gettext. Une exception connue pour cette règle concerne les applications qui sont liées avec des bibliothèques C supplémentaires faisant appel à gettext() ou dcgettext(). Pour ces applications, il peut être nécessaire de lier le domaine du texte, afin que les bibliothèques puissent régionaliser correctement leurs catalogues de messages.