# `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)

  Convierte una cadena de caracteres a un número de punto flotante, siguiendo la configuración `LC_NUMERIC`.

`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 numeros. 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.