# `locale` — Serviços de internacionalização

Código-fonte: Lib/locale.py

O módulo `locale` abre o acesso ao banco de dados de localidade POSIX e funcionalidade. O mecanismo de localidade POSIX permite que os programadores lidem com certas questões culturais em uma aplicação, sem exigir que o programador conheça todas as especificidades de cada país onde o software é executado.

O módulo `locale` é implementado em cima do módulo `_locale`, que por sua vez usa uma implementação a localidade ANSI C se disponível.

O módulo `locale` define a seguinte exceção e funções:

exception locale.Error

  Exceção levantada quando a localidade passada para `setlocale()` não é reconhecida.

locale.setlocale(category, locale=None)

  Se locale for fornecido e não `None`, `setlocale()` modifica a configuração de locale para a category. As categorias disponíveis estão listadas na descrição dos dados abaixo. locale pode ser uma string ou um par, código de idioma e codificação. Uma string vazia especifica as configurações padrão do usuário. Se a modificação da localidade falhar, a exceção `Error` é levantada. Se for bem-sucedido, a nova configuração de localidade será retornada.

  Se locale for um par, ele será convertido em um nome de localidade usando o mecanismo de apelidamento de localidade. O código de idioma tem o mesmo formato de nome da localidade, mas sem codificação e modificador `@`. O código de idioma e a codificação podem ser `None`.

  Se locale for omitido ou `None`, a configuração atual para category é retornada.

  Exemplo:

      >>> import locale
      >>> loc = locale.setlocale(locale.LC_ALL)  # get current locale
      # use German locale; name and availability varies with platform
      >>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
      >>> 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

  `setlocale()` is not thread-safe on most systems. Applications typically start with a call of:

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

  Isso define a localidade de todas as categorias para a configuração padrão do usuário (normalmente especificada na variável de ambiente `LANG`). Se a localidade não for alterada depois disso, o uso de multithreading não deve causar problemas.

locale.localeconv()

  Retorna o banco de dados das convenções locais como um dicionário. Este dicionário possui as seguintes strings como chaves:

  Categoria | Chave | Significado
  --- | --- | ---
  `LC_NUMERIC` | `'decimal_point'` | Caractere de ponto decimal.
  | `'grouping'` | Sequência de números especificando quais posições relativas os `'thousands_sep'` são esperados. Se a sequência for terminada com `CHAR_MAX`, nenhum agrupamento adicional é realizado. Se a sequência termina com um `0`, o tamanho do último grupo é usado repetidamente.
  | `'thousands_sep'` | Caractere usado entre grupos.
  `LC_MONETARY` | `'int_curr_symbol'` | Símbolo internacional de moeda.
  | `'currency_symbol'` | Símbolo local de moeda.
  | `'p_cs_precedes/n_cs_precedes'` | Se o símbolo da moeda precede o valor (para valores positivos ou negativos).
  | `'p_sep_by_space/n_sep_by_space'` | Se o símbolo monetário está separado do valor por um espaço (para valores positivos ou negativos).
  | `'mon_decimal_point'` | Ponto decimal usado para valores monetários.
  | `'frac_digits'` | Número de dígitos fracionários usados na formatação local de valores monetários.
  | `'int_frac_digits'` | Número de dígitos fracionários usados na formatação internacional de valores monetários.
  | `'mon_thousands_sep'` | Separador de grupo usado para valores monetários.
  | `'mon_grouping'` | Equivalente a `'grouping'`, usado para valores monetários.
  | `'positive_sign'` | Símbolo usado para anotar um valor monetário positivo.
  | `'negative_sign'` | Símbolo usado para anotar um valor monetário negativo.
  | `'p_sign_posn/n_sign_posn'` | A posição do sinal (para valores positivos resp. negativos), veja abaixo.

  Todos os valores numéricos podem ser definidos como `CHAR_MAX` para indicar que não há valor especificado nesta localidade.

  Os valores possíveis para `'p_sign_posn'` e `'n_sign_posn'` são dados abaixo.

  Valor | Explicação
  --- | ---
  `0` | A moeda e o valor estão entre parênteses.
  `1` | O sinal deve preceder o valor e o símbolo da moeda.
  `2` | O sinal deve seguir o valor e o símbolo da moeda.
  `3` | O sinal deve preceder imediatamente o valor.
  `4` | O sinal deve seguir imediatamente o valor.
  `CHAR_MAX` | Nada é especificado nesta localidade.

  A função define temporariamente a localidade de `LC_CTYPE` para a localidade de `LC_NUMERIC` ou a localidade de `LC_MONETARY` se as localidades forem diferentes e as strings numéricas ou monetárias não forem ASCII. Esta mudança temporária afeta outras threads.

  Alterado na versão 3.7: A função agora define temporariamente a localidade de `LC_CTYPE` para a localidade de `LC_NUMERIC` em alguns casos.

locale.nl_langinfo(option)

  Retorna algumas informações específicas da localidade em uma string. Esta função não está disponível em todos os sistemas e o conjunto de opções possíveis também pode variar entre as plataformas. Os valores de argumento possíveis são números, para os quais constantes simbólicas estão disponíveis no módulo da localidade.

  A função `nl_langinfo()` aceita uma das seguintes chaves. A maioria das descrições são tiradas da descrição correspondente na biblioteca GNU C.

  locale.CODESET

    Obtém uma string com o nome da codificação de caracteres usada na localidade selecionado.

  locale.D_T_FMT

    Obtém uma string que pode ser usada como uma string de formato para `time.strftime()` para representar a data e a hora de uma maneira específica da localidade.

  locale.D_FMT

    Obtém uma string que pode ser usada como uma string de formato para `time.strftime()` para representar uma data de uma maneira específica da localidade.

  locale.T_FMT

    Obtém uma string que pode ser usada como uma string de formato para `time.strftime()` para representar uma hora de uma maneira específica da localidade.

  locale.T_FMT_AMPM

    Obtém uma string de formato para `time.strftime()` para representar a hora no formato am/pm.

  locale.DAY_1
  locale.DAY_2
  locale.DAY_3
  locale.DAY_4
  locale.DAY_5
  locale.DAY_6
  locale.DAY_7

    Obtém o nome do enésimo dia da semana.

    Nota

    Isso segue a convenção dos EUA de `DAY_1` ser no domingo, não a convenção internacional (ISO 8601) que segunda-feira é o primeiro dia da semana.

  locale.ABDAY_1
  locale.ABDAY_2
  locale.ABDAY_3
  locale.ABDAY_4
  locale.ABDAY_5
  locale.ABDAY_6
  locale.ABDAY_7

    Obtém o nome abreviado do enésimo dia da semana.

  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

    Obtém o nome do enésimo dia do mês.

  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

    Obtém o nome abreviado do enésimo dia do mês.

  locale.RADIXCHAR

    Obtém o caractere separador decimal (ponto decimal, vírgula decimal etc.).

  locale.THOUSEP

    Obtém o caractere separador para milhares (grupos de três dígitos).

  locale.YESEXPR

    Obtém uma expressão regular que pode ser usada com a função regex para reconhecer uma resposta positiva a uma pergunta sim/não.

  locale.NOEXPR

    Obtém uma expressão regular que pode ser usada com a função `regex(3)` para reconhecer uma resposta negativa a uma pergunta sim/não.

    Nota

    As expressões regulares para `YESEXPR` e `NOEXPR` usam uma sintaxe adequada para a função `regex` da biblioteca C, que pode ser diferente da sintaxe usada em `re`.

  locale.CRNCYSTR

    Obtém o símbolo da moeda, precedido por “-” se o símbolo deve aparecer antes do valor, “+” se o símbolo deve aparecer após o valor ou “.” se o símbolo deve substituir o caractere separador decimal.

  locale.ERA

    Obtém uma string que descreva como os anos são contados e exibidos para cada era em um localidade.

    A maioria das localidades não define esse valor. Um exemplo de localidade que define esse valor é o japonês. No Japão, a representação tradicional de datas inclui o nome da época correspondente ao reinado do então imperador.

    Normalmente, não deve ser necessário usar esse valor diretamente. Especificar o modificador `E` em suas strings de formato faz com que a função `time.strftime()` use essas informações. O formato da string retornada é especificado em The Open Group Base Specifications Issue 8, parágrafo 7.3.5.2 LC_TIME C-Language Access.

  locale.ERA_D_T_FMT

    Obtém uma string de formato para `time.strftime()` para representar a data e a hora de uma forma baseada na era específica da localidade.

  locale.ERA_D_FMT

    Obtém uma string de formato para `time.strftime()` para representar uma data em uma forma baseada em era específica da localidade.

  locale.ERA_T_FMT

    Obtém uma string de formato para `time.strftime()` para representar uma hora em uma forma baseada em era específica da localidade.

  locale.ALT_DIGITS

    Obtém uma string consistindo de até 100 símbolos separados por ponto e vírgula usados para representar os valores de 0 a 99 de uma forma específica de localidade. Na maioria das localidades, esta é uma string vazia.

locale.getdefaultlocale([envvars])

  Tenta determinar as configurações de localidade padrão e as retorna como uma tupla na forma `(language code, encoding)`.

  De acordo com POSIX, um programa que não chamou `setlocale(LC_ALL, '')` executa usando a localidade portátil `'C'`. Chamar `setlocale(LC_ALL, '')` permite que ele use a localidade padrão conforme definido pela variável `LANG`. Como não queremos interferir com a configuração de localidade atual, emulamos o comportamento da maneira descrita acima.

  Para manter a compatibilidade com outras plataformas, não apenas a variável `LANG` é testada, mas uma lista de variáveis fornecida como parâmetro envvars. Será utilizado o primeiro encontrado a ser definido. envvars padroniza para o caminho de pesquisa usado no GNU gettext; deve sempre conter o nome da variável `'LANG'`. O caminho de pesquisa do GNU gettext contém `'LC_ALL'`, `'LC_CTYPE'`, `'LANG'` e `'LANGUAGE'`, nesta ordem.

  O código de idioma tem o mesmo formato de nome de localidade, mas sem codificação e modificador `@`. O código de idioma e a codificação podem ser `None` se seus valores não puderem ser determinados. O locale “C” é representado como `(None, None)`.

  Descontinuado desde a versão 3.11, será removido na versão 3.15.

locale.getlocale(category=LC_CTYPE)

  Retorna a configuração atual para a categoria de localidade fornecida como uma tupla contendo o código de idioma e a codificação. category pode ser um dos valores `LC_*`, exceto `LC_ALL`. O padrão é `LC_CTYPE`.

  O código de idioma tem o mesmo formato de nome de localidade, mas sem codificação e modificador `@`. O código de idioma e a codificação podem ser `None` se seus valores não puderem ser determinados. O locale “C” é representado como `(None, None)`.

locale.getpreferredencoding(do_setlocale=True)

  Retorna a codificação da localidade usada para dados de texto, de acordo com as preferências do usuário. As preferências do usuário são expressas de maneira diferente em sistemas diferentes e podem não estar disponíveis programaticamente em alguns sistemas, portanto, essa função retorna apenas uma estimativa.

  Em alguns sistemas, é necessário invocar `setlocale()` para obter as preferências do usuário, portanto, esta função não é segura para thread. Se invocar setlocale não for necessário ou desejado, do_setlocale deve ser definido como `False`.

  No Android ou se o Modo UTF-8 do Python é retornado, sempre retorna `'utf-8'`, a codificação da localidade e o argumento do_setlocale são ignorados.

  A pré-inicialização do Python configura a localidade LC_CTYPE. Veja também tratador de erros e codificação do sistema de arquivos.

  Alterado na versão 3.7: A função agora sempre retorna `"utf-8"` no Android ou se o Modo UTF-8 do Python estiver habilitado.

locale.getencoding()

  Obtém a atual codificação da localidade:

  - No Android e no VxWorks, retorna `"utf-8"`.

  - No Unix, retorna a codificação da localidade `LC_CTYPE` atual. Retorna `"utf-8"` se `nl_langinfo(CODESET)` retornar uma string vazia: por exemplo, se a localidade LC_CTYPE atual não for compatível.

  - No Windows, retorna a página de código ANSI.

  A pré-inicialização do Python configura a localidade LC_CTYPE. Veja também tratador de erros e codificação do sistema de arquivos.

  Este função é semelhante a `getpreferredencoding(False)`, exceto pelo fato de que esta função ignora o Modo UTF-8 do Python.

  Adicionado na versão 3.11.

locale.normalize(localename)

  Retorna um código de localidade normalizado para o nome de localidade fornecido. O código de localidade retornado é formatado para uso com `setlocale()`. Se a normalização falhar, o nome original será retornado inalterado.

  Se a codificação fornecida não for conhecida, o padrão da função é a codificação padrão para o código da localidade, assim como `setlocale()`.

locale.strcoll(string1, string2)

  Compara duas strings de acordo com a configuração atual `LC_COLLATE`. Como qualquer outra função de comparação, retorna um valor negativo ou positivo, ou `0`, dependendo se string1 agrupa antes ou depois de string2 ou é igual a ele.

locale.strxfrm(string)

  Transforma uma string em uma que pode ser usada em comparações com reconhecimento de localidade. Por exemplo, `strxfrm(s1) < strxfrm(s2)` é equivalente a `strcoll(s1, s2) < 0`. Esta função pode ser usada quando a mesma string é comparada repetidamente, por exemplo, ao agrupar uma sequência de strings.

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

  Formata um número val de acordo com a configuração atual do `LC_NUMERIC`. O formato segue as convenções do operador `%`. Para valores de ponto flutuante, o ponto decimal é modificado, se apropriado. Se grouping for `True`, também levará em conta o agrupamento.

  Se monetary for verdadeiro, a conversão usa o separador de milhares monetários e strings de agrupamento.

  Processa especificadores de formatação como em `format % val`, mas leva as configurações de localidade atuais em consideração.

  Alterado na versão 3.7: O parâmetro nomeado monetary foi adicionado.

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

  Formata um número val de acordo com as configurações atuais de `LC_MONETARY`.

  A string retornada inclui o símbolo da moeda se symbol for verdadeiro, que é o padrão. Se grouping for `True` (o que não é o padrão), o agrupamento é feito com o valor. Se international for `True` (o que não é o padrão), o símbolo da moeda internacional será usado.

  Nota

  Esta função não funcionará com a localidade ‘C’, então você deve definir uma localidade via `setlocale()` primeiro.

locale.str(float)

  Formata um número de ponto flutuante usando o mesmo formato da função embutida `str(float)`, mas leva o ponto decimal em consideração.

locale.delocalize(string)

  Converte uma string em uma string numérica normalizada, seguindo as configurações de `LC_NUMERIC`.

  Adicionado na versão 3.5.

locale.localize(string, grouping=False, monetary=False)

  Converte uma string numérica normalizada em uma string formatada, seguindo as configurações de `LC_NUMERIC`.

  Adicionado na versão 3.10.

locale.atof(string, func=float)

  Converte uma string para um número, de acordo com o valor da constante `LC_NUMERIC`, chamando func com o resultado da chamada à `delocalize()` em string.

locale.atoi(string)

  Converte uma string em um número inteiro, seguindo as convenções de `LC_NUMERIC`.

locale.LC_CTYPE

  Categoria da localidade para as funções de tipo de caracteres. Mais importante ainda, essa categoria define a codificação do texto, ou seja, como os bytes são interpretado como pontos de código Unicode. Consulte PEP 538 e PEP 540 para saber como essa variável pode ser automaticamente coagida para `C.UTF-8` para evitar problemas criados por configurações inválidas em contêineres ou configurações incompatíveis passadas por conexões remotas com SSH.

  O Python não usa internamente funções de transformação de caracteres dependente de localidade do `ctype.h`. Em vez disso, `pyctype.h` fornece equivalentes independentes de localidade como `Py_TOLOWER`.

locale.LC_COLLATE

  Categoria da localidade para classificação de strings. As funções `strcoll()` e `strxfrm()` do módulo `locale` são afetadas.

locale.LC_TIME

  Categoria da localidade para a formatação de hora. A função `time.strftime()` segue essas convenções.

locale.LC_MONETARY

  Categoria da localidade para formatação de valores monetários. As opções disponíveis estão disponíveis na função `localeconv()`.

locale.LC_MESSAGES

  Categoria da localidade para exibição de mensagens. Python atualmente não oferece suporte a mensagens com reconhecimento de localidade específicas da aplicação. Mensagens exibidas pelo sistema operacional, como aquelas retornadas por `os.strerror()` podem ser afetadas por esta categoria.

  Esse valor pode não estar disponível em sistemas operacionais que não estejam em conformidade com o padrão POSIX, principalmente o Windows.

locale.LC_NUMERIC

  Categoria da localidade para formatação de números. As funções `format_string()`, `atoi()`, `atof()` e `str()` do módulo `locale` são afetadas por essa categoria. Todas as outras operações de formatação numérica não são afetadas.

locale.LC_ALL

  Combinação de todas as configurações da localidade. Se este sinalizador for usado quando a localidade for alterada, a configuração da localidade para todas as categorias será tentada. Se isso falhar para qualquer categoria, nenhuma categoria é alterada. Quando a localidade é recuperada usando este sinalizador, uma string indicando a configuração para todas as categorias é retornada. Esta string pode ser usada posteriormente para restaurar as configurações.

locale.CHAR_MAX

  Esta é uma constante simbólica usada para diferentes valores retornados por `localeconv()`.

## Histórico, detalhes, dicas, dicas e advertências

O padrão C define a localidade como uma propriedade de todo o programa que pode ser relativamente cara para alterar. Além disso, algumas implementações são interrompidas de forma que mudanças frequentes de localidade podem causar despejos de memória. Isso torna a localidade um tanto dolorosa de usar corretamente.

Inicialmente, quando um programa é iniciado, a localidade é a localidade `C`, não importa qual a localidade preferida do usuário. Há uma exceção: a categoria `LC_CTYPE` é alterada na inicialização para definir a codificação de localidade atual para a codificação de localidade preferida do usuário. O programa deve dizer explicitamente que deseja as configurações de localidade preferidas do usuário para outras categorias chamando `setlocale(LC_ALL, '')`.

Geralmente é uma má ideia chamar `setlocale()` em alguma rotina de biblioteca, já que como efeito colateral afeta todo o programa. Salvar e restaurar é quase tão ruim: é caro e afeta outras threads que são executadas antes de as configurações serem restauradas.

Se, ao codificar um módulo para uso geral, você precisa de uma versão independente da localidade de uma operação que é afetada pela localidade (como certos formatos usados com `time.strftime()`), você terá que encontrar uma maneira de faça isso sem usar a rotina de biblioteca padrão. Melhor ainda é se convencer de que não há problema em usar as configurações da localidade. Apenas como último recurso, você deve documentar que seu módulo não é compatível com configurações de localidade não-`C`.

A única maneira de realizar operações numéricas de acordo com a localidade é usar as funções especiais definidas por este módulo: `atof()`, `atoi()`, `format_string()`, `str()`.

Não há como realizar conversões de maiúsculas e minúsculas e classificações de caracteres de acordo com a localidade. Para strings de texto (Unicode), isso é feito de acordo com o valor do caractere apenas, enquanto para strings de byte, as conversões e classificações são feitas de acordo com o valor ASCII do byte e bytes cujo bit alto está definido (ou seja, bytes não ASCII ) nunca são convertidos ou considerados parte de uma classe de caracteres, como letras ou espaços em branco.

## Nomes de localidades

O formato do nome de localidade depende da plataforma, e o conjunto de locais suportados pode depender da configuração do sistema.

Em plataformas Posix, isso geralmente tem o formato [1]:

         language ["_" territory] ["." charset] ["@" modifier]

onde language é um código de idioma de duas ou três letras da ISO 639, territory é um código de país ou região de duas letras da ISO 3166, charset é uma codificação de localidade e modifier é um nome de script, uma subtag de idioma, um identificador de ordem de classificação ou outro modificador de localidade (por exemplo, “latin”, “valencia”, “stroke” e “euro”).

No Windows, vários formatos são suportados. [2] [3] Um subconjunto de tags IETF BCP 47:

         language ["-" script] ["-" territory] ["." charset]
         language ["-" script] "-" territory "-" modifier

onde language e territory têm o mesmo significado que em Posix, script é um código de script de quatro letras da ISO 15924 e modifier é uma subtag de idioma, um identificador de ordem de classificação ou modificador personalizado (por exemplo, “valencia”, “stroke” ou “x-python”). São aceitos os separadores hífen (`'-'`) e sublinhado (`'_'`). Somente a codificação UTF-8 é permitida para tags BCP 47.

O Windows também oferece suporte a nomes de localidade no formato:

         language ["_" territory] ["." charset]

onde language e territory são nomes completos, como “English” e “United States”, e charset é um número de página de código (por exemplo, “1252”) ou UTF-8. Só é aceito o separador sublinhado neste formato.

A localidade “C” é aceita em todas as plataformas.

[1]

IEEE Std 1003.1-2024; 8.2 Internationalization Variables

[2]

Nomes de localidade, idiomas e strings de país/região do UCRT

[3]

Nomes de localidade

## Para escritores de extensão e programas que incorporam Python

Módulos de extensão nunca devem chamar `setlocale()`, exceto para descobrir qual é a localidade atual. Mas uma vez que o valor de retorno só pode ser usado portavelmente para restaurá-lo, isso não é muito útil (exceto talvez para descobrir se a localidade é ou não `C`).

Quando o código Python usa o módulo `locale` para alterar a localidade, isso também afeta a aplicação de incorporação. Se a aplicação de incorporação não quiser que isso aconteça, ele deve remover o módulo de extensão `_locale` (que faz todo o trabalho) da tabela de módulos embutidos no arquivo `config.c` e certificar-se de que o módulo `_locale` não está acessível como uma biblioteca compartilhada.

## Acesso a catálogos de mensagens

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)

O módulo locale expõe a interface gettext da biblioteca C em sistemas que fornecem essa interface. Consiste nas funções `gettext()`, `dgettext()`, `dcgettext()`, `textdomain()`, `bindtextdomain()` e `bind_textdomain_codeset()`. Elas são semelhantes às mesmas funções no módulo `gettext`, mas usam o formato binário da biblioteca C para catálogos de mensagens e os algoritmos de pesquisa da biblioteca C para localizar catálogos de mensagens.

As aplicações Python normalmente não precisam invocar essas funções e devem usar `gettext` em seu lugar. Uma exceção conhecida a esta regra são os aplicativos que se vinculam a bibliotecas C adicionais que invocam internamente `gettext` ou `dcgettext`. Para essas aplicações, pode ser necessário vincular o domínio de texto, para que as bibliotecas possam localizar adequadamente seus catálogos de mensagens.