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çãoError
é 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 deimport 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
'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 comCHAR_MAX
, nenhum agrupamento adicional é realizado. Se a sequência termina com um0
, o tamanho do último grupo é usado repetidamente.'thousands_sep'
Caractere usado entre grupos.
'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
Explanaçã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 deLC_NUMERIC
ou a localidade deLC_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 deLC_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.
-
DAY_1 ... 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.
-
ABDAY_1 ... ABDAY_7
Obtém o nome abreviado do enésimo dia da semana.
-
MON_1 ... MON_12
Obtém o nome do enésimo dia do mês.
-
ABMON_1 ... 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.
Nota
A expressão está na sintaxe adequada para a função
regex()
da biblioteca C, que pode ser diferente da sintaxe usada emre
.
-
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.
-
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çãotime.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 representação de até 100 valores usada para representar os valores de 0 a 99.
-
-
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'
. Chamarsetlocale(LC_ALL, '')
permite que ele use a localidade padrão conforme definido pela variávelLANG
. 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 serNone
se seus valores não puderem ser determinados.
-
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_*
, excetoLC_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 serNone
se seus valores não puderem ser determinados.
-
locale.
getpreferredencoding
(do_setlocale=True)¶ Retorna a codificação 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 comoFalse
.No Android ou no modo UTF-8 (opção
-X
utf8
), sempre retorna'UTF-8'
, a localidade e o argumento do_setlocale são ignorados.Alterado na versão 3.7: A função agora sempre retorna
UTF-8
no Android ou se o modo UTF-8 estiver habilitado.
-
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.
resetlocale
(category=LC_ALL)¶ Define a localidade para category para a configuração padrão.
A configuração padrão é determinada chamando
getdefaultlocale()
. category assume como padrãoLC_ALL
.
-
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, ou0
, 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 astrcoll(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 de
LC_NUMERIC
. O formato segue as convenções do operador%
. Para valores de ponto flutuante, o ponto decimal é modificado, se apropriado. Se grouping for verdadeiro, também leva o agrupamento em consideração.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.
format
(format, val, grouping=False, monetary=False)¶ Observe que esta função funciona como
format_string()
, mas só funcionará para exatamente um especificador%char
. Por exemplo,'%f'
e'%.0f'
são especificadores válidos, mas'%f KiB'
não é.Para strings de formato inteiras, use
format_string()
.Obsoleto desde a versão 3.7: Use
format_string()
.
-
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 verdadeiro (o que não é o padrão), o agrupamento é feito com o valor. Se international for verdadeiro (o que não é o padrão), o símbolo da moeda internacional será usado.
Observe que 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
.Novo na versão 3.5.
-
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 caractere. Dependendo das configurações desta categoria, as funções do módulo
string
lidando com diferença de maiúsculo e minúsculo mudam seu comportamento.
-
locale.
LC_COLLATE
¶ Categoria da localidade para classificação de strings. As funções
strcoll()
estrxfrm()
do módulolocale
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.
-
locale.
LC_NUMERIC
¶ Categoria da localidade para formatação de números. As funções
format()
,atoi()
,atof()
estr()
do módulolocale
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() # 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
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()
, 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)¶
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.