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 iterável de duas strings (código de idioma e codificação). Se for um iterável, ele é convertido em um nome de local usando o mecanismo de alias da localidade. 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 omitido ou None, a configuração atual para category é retornada.

setlocale() não é seguro para thread na maioria dos sistemas. As aplicações normalmente começam com uma chamada de

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 represente a era usada na localidade atual.

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 este valor diretamente. Especificar o modificador E em suas strings de formato faz com que a função time.strftime() use esta informação. O formato da string retornada não é especificado e, portanto, você não deve presumir que tem conhecimento dele em sistemas diferentes.

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.

Exceto pelo código 'C', o código do idioma corresponde a RFC 1766. language code e encoding podem ser None se seus valores não puderem ser determinados.

Deprecated since version 3.11, will be removed in version 3.15.

locale.getlocale(category=LC_CTYPE)

Retorna a configuração atual para a categoria de localidade fornecida como uma sequência contendo language code, encoding. category pode ser um dos valores LC_*, exceto LC_ALL. O padrão é LC_CTYPE.

Exceto pelo código 'C', o código do idioma corresponde a RFC 1766. language code e encoding podem ser None se seus valores não puderem ser determinados.

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, um pyctype.h interno 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().

Exemplo:

>>> import locale
>>> loc = locale.getlocale()  # obtém localidade atual
# usa localidade de alemão; o nome pode variar conforme plataforma
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo')  # compara uma string contendo um umlaut
>>> locale.setlocale(locale.LC_ALL, '')   # usa a localidade preferida do usuário
>>> locale.setlocale(locale.LC_ALL, 'C')  # usa a localidade padrão (C)
>>> locale.setlocale(locale.LC_ALL, loc)  # restaura localidade salva

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.

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.