"locale" --- Servicios de internacionalización
**********************************************

**Source code:** Lib/locale.py

======================================================================

El módulo "locale" abre el acceso a la base de datos y la
funcionalidad de POSIX locale. El mecanismo POSIX locale permite a los
programadores tratar ciertos problemas culturales en una aplicación,
sin requerir que el programador conozca todos los detalles de cada
país donde se ejecuta el software.

El módulo "locale" se implementa en la parte superior del módulo
"_locale", que a su vez utiliza una implementación de configuración
regional ANSI C si está disponible.

El módulo "locale" define las siguientes excepciones y funciones:

exception locale.Error

   Cuando el *locale* pasado a "setlocale()" no es reconocido, se
   lanza una excepción.

locale.setlocale(category, locale=None)

   Si *locale* está dado y no es "None", "setlocale()" modifica la
   configuración de localización para *category*. Las categorías
   disponibles se enumeran en la descripción de los datos que figura a
   continuación. *locale* puede ser una cadena de caracteres, o una
   iterable de dos cadenas de caracteres (código de idioma y
   codificación). Si es iterable, se convierte a un nombre de
   configuración regional usando el motor de *aliasing* de la
   configuración regional. Una cadena de caracteres vacía especifica
   la configuración predeterminada del usuario. Si la modificación de
   la localización falla, se genera la excepción  "Error" . Si tiene
   éxito, se retorna la nueva configuración de localización.

   Si se omite *locale* o es "None", se retorna la configuración
   actual para *category*.

   "setlocale()" no es seguro para subprocesos en la mayoría de los
   sistemas. Las aplicaciones normalmente comienzan con una llamada de

      import locale
      locale.setlocale(locale.LC_ALL, '')

   Esto establece la configuración regional de todas las categorías en
   la configuración predeterminada del usuario (normalmente
   especificada en la variable de entorno "LANG" ).  Si la
   configuración regional no se cambia a partir de entonces, el uso de
   multiprocesamiento, no debería causar problemas.

locale.localeconv()

   retorna la base de datos de las convenciones locales como
   diccionario. Este diccionario tiene las siguientes cadenas de
   caracteres como claves:

   +------------------------+---------------------------------------+----------------------------------+
   | Categoría              | Clave                                 | Significado                      |
   |========================|=======================================|==================================|
   | "LC_NUMERIC"           | "'decimal_point'"                     | Carácter de punto decimal.       |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'agrupación'"                        | Secuencia de números que         |
   |                        |                                       | especifica qué posiciones        |
   |                        |                                       | relativas se espera el           |
   |                        |                                       | "'miles_sep'". Si la secuencia   |
   |                        |                                       | termina con "CHAR_MAX", no se    |
   |                        |                                       | realiza ninguna agrupación       |
   |                        |                                       | adicional. Si la secuencia       |
   |                        |                                       | termina con un "0", el último    |
   |                        |                                       | tamaño de grupo se usa           |
   |                        |                                       | repetidamente.                   |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'thousands_sep'"                     | Carácter utilizado entre grupos. |
   +------------------------+---------------------------------------+----------------------------------+
   | "LC_MONETARY"          | "'int_curr_symbol'"                   | Símbolo de moneda internacional. |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'currency_symbol'"                   | Símbolo de moneda local.         |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'p_cs_precedes/n_cs_precedes'"       | Si el símbolo de moneda precede  |
   |                        |                                       | al valor (para valores positivos |
   |                        |                                       | o negativos).                    |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'p_sep_by_space/n_sep_by_space'"     | Si el símbolo de moneda está     |
   |                        |                                       | separado del valor por un        |
   |                        |                                       | espacio (para valores positivos  |
   |                        |                                       | o negativos).                    |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'mon_decimal_point'"                 | Punto decimal utilizado para     |
   |                        |                                       | valores monetarios.              |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'frac_digits'"                       | Número de dígitos fraccionarios  |
   |                        |                                       | utilizados en el formateo local  |
   |                        |                                       | de valores monetarios.           |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'int_frac_digits'"                   | Número de dígitos fraccionarios  |
   |                        |                                       | utilizados en el formateo        |
   |                        |                                       | internacional de valores         |
   |                        |                                       | monetarios.                      |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'mon_thousands_sep'"                 | Separador de grupo utilizado     |
   |                        |                                       | para valores monetarios.         |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'mon_grouping'"                      | Equivalente a "'grouping'",      |
   |                        |                                       | utilizada para valores           |
   |                        |                                       | monetarios.                      |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'positive_sign'"                     | Símbolo utilizado para anotar un |
   |                        |                                       | valor monetario positivo.        |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'negative_sign'"                     | Símbolo utilizado para anotar un |
   |                        |                                       | valor monetario negativo.        |
   +------------------------+---------------------------------------+----------------------------------+
   |                        | "'p_sign_posn/n_sign_posn'"           | La posición del signo (para      |
   |                        |                                       | respuestas positivas. valores    |
   |                        |                                       | negativos), ver abajo.           |
   +------------------------+---------------------------------------+----------------------------------+

   Todos los valores numéricos se pueden establecer a "CHAR_MAX" para
   indicar que no hay ningún valor especificado en esta configuración
   regional.

   Los valores posibles para "'p_sign_posn'" y `` 'n_sign_posn'`` se
   dan a continuación.

   +----------------+-------------------------------------------+
   | Valor          | Explicación                               |
   |================|===========================================|
   | "0"            | Moneda y valor están rodeados por         |
   |                | paréntesis.                               |
   +----------------+-------------------------------------------+
   | "1"            | El signo debe preceder al valor y al      |
   |                | símbolo de moneda.                        |
   +----------------+-------------------------------------------+
   | "2"            | El signo debe seguir el valor y el        |
   |                | símbolo de moneda.                        |
   +----------------+-------------------------------------------+
   | "3"            | El signo debe preceder inmediatamente al  |
   |                | valor.                                    |
   +----------------+-------------------------------------------+
   | "4"            | El signo debe seguir inmediatamente al    |
   |                | valor.                                    |
   +----------------+-------------------------------------------+
   | "CHAR_MAX"     | No se especifica nada en esta             |
   |                | configuración regional.                   |
   +----------------+-------------------------------------------+

   La función establece temporalmente el "LC_CTYPE" de configuración
   regional al "LC_NUMERIC" de la configuración regional o el
   "LC_MONETARY" de la configuración local si las configuraciones
   locales son diferentes y las cadenas de caracteres numéricas o
   monetarias no son ASCII. Este cambio temporal afecta a otros hilos.

   Distinto en la versión 3.7: La función ahora establece
   temporalmente el "LC_CTYPE" de la configuración local al
   "LC_NUMERIC" en algunos casos.

locale.nl_langinfo(option)

   retorna información específica de la configuración regional como
   una cadena de caracteres.  Esta función no está disponible en todos
   los sistemas, y el conjunto de opciones posibles también puede
   variar entre plataformas.  Los posibles valores de argumento son
   números, para los cuales las constantes simbólicas están
   disponibles en el módulo de configuración regional.

   La función "nl_langinfo()" acepta una de las siguientes claves.  La
   mayoría de las descripciones están tomadas de la descripción
   correspondiente en la biblioteca C de GNU.

   locale.CODESET

      Obtiene una cadena de caracteres con el nombre de la
      codificación de caracteres utilizada en la configuración
      regional seleccionada.

   locale.D_T_FMT

      Obtiene una cadena de caracteres que se puede utilizar como
      cadena de caracteres de formato para "time.strftime()" para
      representar la fecha y la hora de una manera específica de la
      configuración regional.

   locale.D_FMT

      Obtiene una cadena de caracteres que se puede utilizar como
      cadena de formato para "time.strftime()" para representar una
      fecha de una manera específica de la configuración regional.

   locale.T_FMT

      Obtiene una cadena de caracteres que se puede utilizar como
      cadena de formato para "time.strftime()" para representar un
      tiempo de una manera específica de la configuración regional.

   locale.T_FMT_AMPM

      Obtiene una cadena de caracteres de formato para
      "time.strftime()" para representar el tiempo en el formato
      am/pm.

   DAY_1 ... DAY_7

      Consigue el nombre del n-ésimo día de la semana.

      Nota:

        Esto sigue la convención estadounidense de "DAY_1" siendo
        domingo, no la convención internacional (ISO 8601) que el
        lunes es el primer día de la semana.

   ABDAY_1 ... ABDAY_7

      Obtener el nombre abreviado del n-ésimo día de la semana.

   MON_1 ... MON_12

      Obtener el nombre del n-ésimo mes.

   ABMON_1 ... ABMON_12

      Obtener el nombre abreviado del enésimo mes.

   locale.RADIXCHAR

      Obtener el carácter radical (punto decimal, coma decimal, etc.).

   locale.THOUSEP

      Obtener el carácter separador de miles (grupos de tres dígitos).

   locale.YESEXPR

      Obtener una expresión regular que se pueda usar con la función
      regex para reconocer una respuesta positiva a una pregunta de sí
      / no.

      Nota:

        La expresión está en la sintaxis adecuada para la función
        "regex()" de la biblioteca C, que podría diferir de la
        sintaxis utilizada en "re".

   locale.NOEXPR

      Obtener una expresión regular que se puede usar con la función
      regex(3) para reconocer una respuesta negativa a una pregunta de
      sí/no.

   locale.CRNCYSTR

      Obtener el símbolo de moneda, precedido por "-" si el símbolo
      debe aparecer antes del valor, "+" si el símbolo debe aparecer
      después del valor, o "." si el símbolo debe reemplazar el
      carácter raíz.

   locale.ERA

      Obtener una cadena de caracteres que represente la era utilizada
      en la configuración regional actual.

      La mayoría de las configuraciones regionales no definen este
      valor.  Un ejemplo de una localidad que sí define este valor es
      la japonesa.  En Japón, la representación tradicional de fechas
      incluye el nombre de la época correspondiente al reinado del
      entonces emperador.

      Normalmente no debería ser necesario utilizar este valor
      directamente. Especificar el modificador "E" en sus cadenas de
      caracteres de formato hace que la función "time.strftime()" use
      esta información. El formato de la cadena de caracteres
      retornada no está especificado, y por lo tanto no debe asumir
      conocimiento de él en diferentes sistemas.

   locale.ERA_D_T_FMT

      Obtener una cadena de caracteres de formato para
      "time.strftime()" para representar la fecha y la hora de una
      manera específica de la era.

   locale.ERA_D_FMT

      Obtener una cadena de caracteres de formato para
      "time.strftime()" para representar una fecha de una manera
      basada en una era específica.

   locale.ERA_T_FMT

      Obtener una cadena de caracteres de formato para
      "time.strftime()" para representar una hora de una manera basada
      en una era específica.

   locale.ALT_DIGITS

      Obtener una representación de hasta 100 valores utilizados para
      representar los valores 0 a 99.

locale.getdefaultlocale([envvars])

   Intenta determinar la configuración regional por defecto y los
   retorna como una tupla del formulario "(código de idioma,
   codificación)".

   De acuerdo con POSIX, un programa que no ha llamado a
   "setlocale(LC_ALL, '')" se ejecuta utilizando la configuración
   regional portátil `` 'C '`` . Llamar a "setlocale(LC_ALL, ' ')" le
   permite usar la configuración regional predeterminada definida por
   la variable "LANG" . Dado que no queremos interferir con la
   configuración de configuración regional actual, emulamos el
   comportamiento de la manera descrita anteriormente.

   Para mantener la compatibilidad con otras plataformas, no sólo se
   prueba la variable "LANG" sino una lista de variables dadas como
   parámetro *envvars*.  Se utilizará la primera que se encuentre
   definida.  *envvars* por defecto a la ruta de búsqueda utilizada en
   GNU gettext; siempre debe contener el nombre de la variable "'LANG
   '".  La ruta de búsqueda GNU gettext contiene "'LC_ALL '",
   "'LC_CTYPE '", "'LANG '" y "'LANGUAGE '", en ese orden.

   Excepto por el código "'C'", el código de lenguaje corresponde a
   **RFC 1766**. *language code* y *encoding* pueden ser "None" si sus
   valores no pueden determinarse.

locale.getlocale(category=LC_CTYPE)

   retorna la configuración actual para la categoría de configuración
   regional dada como secuencia que contiene *language code*,
   *coding*. *category* puede ser uno de los valores "LC_  *" excepto
   "LC_ALL".  Por defecto es "LC_CTYPE".

   Excepto por el código "'C'", el código de lenguaje corresponde a
   **RFC 1766**. *language code* y *encoding* pueden ser "None" si sus
   valores no pueden determinarse.

locale.getpreferredencoding(do_setlocale=True)

   retorna la codificación utilizada para los datos de texto, según
   las preferencias del usuario.  Las preferencias del usuario se
   expresan de manera diferente en diferentes sistemas, y puede que no
   estén disponibles programáticamente en algunos sistemas, por lo que
   esta función solo retorna una suposición.

   En algunos sistemas, es necesario invocar "setlocale()" para
   obtener las preferencias del usuario, por lo que esta función no es
   segura para subprocesos. Si invocar *setlocale* no es necesario o
   deseado, *do_setlocale* se debe ajustar a "False".

   En Android o en el modo UTF-8 ("-X" "utf8" opción), siempre retorna
   "'UTF-8 '", se ignoran la configuración regional y el argumento
   *do_setlocale*.

   Distinto en la versión 3.7: La función ahora siempre retorna
   "UTF-8" en Android o si el modo UTF-8 está habilitado.

locale.normalize(localename)

   retorna un código de configuración regional normalizado para el
   nombre configuración regional dado.  El código de configuración
   regional retornado está formateado para usarse con "setlocale()".
   Si la normalización falla, el nombre original se retorna sin
   cambios.

   Si no se conoce la codificación dada, la función por defecto
   codifica el código de configuración regional como "setlocale()".

locale.resetlocale(category=LC_ALL)

   Establece la configuración regional de *category* a la
   configuración predeterminada.

   La configuración predeterminada se determina llamando a
   "getdefaultlocale()". *category* por defecto a "LC_ALL".

locale.strcoll(string1, string2)

   Compara dos cadenas según la configuración actual "LC_COLLATE" .
   Como cualquier otra función de comparación, retorna un valor
   negativo o positivo, o "0", dependiendo de si *string1* compila
   antes o después de *string2* o es igual a él.

locale.strxfrm(string)

   Transforma una cadena en una que se puede utilizar en comparaciones
   de localización.  Por ejemplo, "strxfrm(s1) < strxfrm(s2)" es
   equivalente a "strcoll(s1, s2) < 0".  Esta función se puede
   utilizar cuando la misma cadena se compara repetidamente, p. ej.,
   al agrupar una secuencia de cadenas.

locale.format_string(format, val, grouping=False, monetary=False)

   Formatea un número *val* según la configuración actual "LC_NUMERIC"
   . El formato sigue las convenciones del operador "%". Para los
   valores en coma flotante, el punto decimal se modifica si procede.
   Si *grouping* es verdadero, también se tiene en cuenta el
   agrupamiento.

   Si *monetary* es verdadero, la conversión utiliza separador
   monetario de miles y cadenas de caracteres de agrupación.

   Procesa especificadores de formato como en "format % val", pero
   tiene en cuenta los ajustes de configuración regional actuales.

   Distinto en la versión 3.7: Se añadió el parámetro de la palabra
   clave *monetary*.

locale.format(format, val, grouping=False, monetary=False)

   Tenga en cuenta que esta función funciona como "format_string()"
   pero sólo funcionará para exactamente un especificador "%char".
   Por ejemplo, "'%f'" y "'%. 0f'" son especificadores válidos, pero
   "'%f KiB'" no lo es.

   Para cadenas de caracteres de formato completas, use
   "format_string()".

   Obsoleto desde la versión 3.7: Use "format_string()" en su lugar.

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

   Formatea un número *val* según la configuración actual
   "LC_MONETARY" .

   La cadena de caracteres retornada incluye el símbolo de moneda si
   *symbol* es verdadero, que es el valor predeterminado. Si
   *grouping* es verdadero (que no es el valor predeterminado), la
   agrupación se realiza con el valor. Si *international* es verdadero
   (que no es el valor predeterminado), se utiliza el símbolo de
   moneda internacional.

   Tenga en cuenta que esta función no funcionará con la configuración
   regional  'C', por lo que primero debe establecer una configuración
   regional (*locale*) a través de "setlocale()" .

locale.str(float)

   Formatea un número de punto flotante usando el mismo formato que la
   función integrada "str(float)", pero toma en cuenta el punto
   decimal.

locale.delocalize(string)

   Convierte una cadena de caracteres en una cadena de números
   normalizada, siguiendo la configuración "LC_NUMERIC".

   Nuevo en la versión 3.5.

locale.atof(string, func=float)

   Converts a string to a number, following the "LC_NUMERIC" settings,
   by calling *func* on the result of calling "delocalize()" on
   *string*.

locale.atoi(string)

   Convierte una cadena de caracteres a un entero, siguiendo las
   convenciones "LC_NUMERIC" .

locale.LC_CTYPE

   Configuración regional de localización para las funciones de tipo
   caracter.  Dependiendo de la configuración de esta categoría, las
   funciones del módulo "string" que se ocupan de casos cambian su
   comportamiento.

locale.LC_COLLATE

   Categoría de configuración regional para ordenar cadenas de
   caracteres.  Las funciones "strcoll()" y "strxfrm()" del módulo
   "locale" están afectadas.

locale.LC_TIME

   Categoría de configuración regional para el formateo de hora.  La
   función "time.strftime()" sigue estas convenciones.

locale.LC_MONETARY

   Categoría de configuración regional para el formateo de valores
   monetarios.  Las opciones disponibles están disponibles en la
   función "localeconv()" .

locale.LC_MESSAGES

   Categoría de configuración regional para visualización de mensajes.
   Python actualmente no admite mensajes de configuración regional
   específicos de la aplicación.  Los mensajes mostrados por el
   sistema operativo, como los retornados por "os.strerror()" podrían
   verse afectados por esta categoría.

locale.LC_NUMERIC

   Categoría de configuración regional para formateo de números.  Las
   funciones " format()", "atoi()", "atof()" y "str()" del módulo
   "locale" están afectados por esa categoría.  Todas las demás
   operaciones de formato numérico no están afectadas.

locale.LC_ALL

   Combinación de todos los ajustes de configuración regional.  Si se
   utiliza este indicador cuando se cambia la localización, se intenta
   establecer la localización para todas las categorías. Si eso falla
   para cualquier categoría, ninguna categoría se cambia en absoluto.
   Cuando la configuración regional se recupera usando este indicador,
   se retorna una cadena de caracteres que indica la configuración
   para todas las categorías. Esta cadena de caracteres se puede usar
   más tarde para restaurar la configuración.

locale.CHAR_MAX

   Esta es una constante simbólica utilizada para diferentes valores
   retornados por "localeconv()".

Ejemplo:

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


Segundo plano, detalles, indicaciones, consejos y advertencias
==============================================================

El estándar C define la configuración regional como una propiedad de
todo el programa que puede ser relativamente costosa de cambiar.
Además de eso, alguna implementación se rompe de tal manera que los
cambios de configuración local frecuentes pueden causar volcados de
núcleo.  Esto hace que la configuración regional sea algo dolorosa de
usar correctamente.

Inicialmente, cuando se inicia un programa, la configuración regional
es la configuración regional "C", no importa cuál sea la configuración
regional preferida por el usuario.  Hay una excepción: la categoría
"LC_CTYPE" se cambia al inicio para establecer la codificación de la
configuración regional actual en la codificación de configuración
regional preferida del usuario. El programa debe decir explícitamente
que quiere la configuración regional preferida del usuario para otras
categorías llamando a "setlocale(LC_ALL, '')".

Generalmente es una mala idea llamar "setlocale()" en alguna rutina de
biblioteca, ya que como efecto secundario afecta a todo el programa.
Guardar y restaurar es casi igual de malo: es caro y afecta a otros
hilos que se ejecutan antes de que los ajustes se hayan restaurado.

Si, al codificar un módulo para uso general, se necesita una versión
configuración regional independiente de una operación que se ve
afectada por la localización (como ciertos formatos utilizados con
"time.strftime()"), tendrá que encontrar una manera de hacerlo sin
usar la rutina de biblioteca estándar.  Aún mejor es convencerse a sí
mismo de que el uso de la configuración regional está bien.  Sólo como
último recurso debe documentar que su módulo no es compatible con la
configuración regional no-   "C".

La única manera de realizar operaciones numéricas según la
configuración regional es utilizar las funciones especiales definidas
por este módulo: "atof()", "atoi()", " formato()", " str()".

No hay manera de realizar conversiones de casos y clasificaciones de
caracteres de acuerdo a la configuración regional.  Para cadenas de
texto (Unicode) estas se hacen de acuerdo con el valor de carácter
solamente, mientras que para cadenas de bytes, las conversiones y
clasificaciones se hacen de acuerdo con el valor ASCII del byte, y
bytes cuyo bit alto se establece (es decir, bytes no ASCII) nunca se
convierten o se consideran parte de una clase de caracteres como letra
o espacio en blanco.


Para escritores de extensión y programas que incrustan Python
=============================================================

Los módulos de extensión nunca deben llamar a "setlocale()", excepto
para averiguar cuál es la configuración regional actual.  Pero dado
que el valor de retorno sólo se puede utilizar portablemente para
restaurarlo, eso no es muy útil (excepto quizás para averiguar si la
localización es o no es "C").

Cuando el código de Python utiliza el módulo "locale" para cambiar la
configuración regional, esto también afecta a la aplicación de
incrustación.  Si la aplicación de incrustación no quiere que esto
suceda, debe eliminar el módulo de extensión "_locale" (que hace todo
el trabajo) de la tabla de módulos incorporados en el archivo de
configuración "config.c", y asegúrese de que el módulo "_locale" no es
accesible como una biblioteca compartida.


Acceso a los catálogos de mensajes
==================================

locale.gettext(msg)

locale.dgettext(domain, msg)

locale.dcgettext(domain, msg, category)

locale.textdomain(domain)

locale.bindtextdomain(domain, dir)

El módulo de configuración regional expone la interfaz *gettext* de la
biblioteca C en sistemas que proporcionan esta interfaz.  Consta de
las funciones "gettext()", "dgettext()", "dcgettext()",
"textdomain()", "binddomaintext()", y "bind_textdomain_codeset()".
Estas son similares a las mismas funciones en el módulo "gettext" ,
pero usan el formato binario de la biblioteca C para catálogos de
mensajes, y los algoritmos de búsqueda de la biblioteca C para
localizar catálogos de mensajes.

Las aplicaciones de Python normalmente no deberían tener que invocar
estas funciones, y deberían usar "gettext" en su lugar.  Una excepción
conocida a esta regla son las aplicaciones que enlazan con bibliotecas
C adicionales que invocan internamente "gettext()" o "dcgettext()".
Para estas aplicaciones, puede ser necesario vincular el dominio de
texto, para que las bibliotecas puedan localizar adecuadamente sus
catálogos de mensajes.
