11 De Junho De 2025

Como converter datas para o formato brasileiro: guia prático

Muita gente trava na hora de formatar datas corretamente em scripts Python, especialmente quando precisa outputar no padrão DD de MMMM de AAAA que usamos aqui. Vou explicar direto, com código que funciona. A data 11 de junho de 2025 serve como exemplo perfeito porque tem um mês com nome completo ("junho") que frequentemente causa erro de digitação — as pessoas escrevem "junho" com H no final ou confundem com "Jun" do inglês. Isso gera bugs silenciosos em sistemas que precisam comparar datas em português com bancos de dados em UTC. O método mais confiável que eu uso:

Se você está usando Python com a biblioteca pendulum, que resolve metade dos problemas que o módulo nativo datetime traz:

import pendulum

data = pendulum.parse("2025-06-11")
formato_br = data.format("DD 'de' MMMM 'de' YYYY", locale="pt_br")
print(formato_br)
Retorna: 11 de junho de 2025

Se não quiser instalar pendulum, o strftime nativo funciona mas tem uma armadilha importante: ele só formata corretamente se o locale do sistema operacional estiver configurado para português. Em servidores AWS, Docker containers limpos, ou GitHub Actions, o locale padrão é geralmente C/POSIX, e %B retorna "June" em vez de "junho". Eu descobri isso da pior forma possível quando um relatório financeiro saiu com mês em inglês para um cliente brasileiro e ninguém percebeu até a assinatura renewal. A workaround que eu uso desde então, que funciona em qualquer ambiente:

MONTHS_PT = [
    "janeiro", "fevereiro", "março", "abril",
    "maio", "junho", "julho", "agosto",
    "setembro", "outubro", "novembro", "dezembro"
]

from datetime import datetime

data = datetime(2025, 6, 11)
mes = MONTHS_PT[data.month - 1]
formato_br = data.strftime(f"%d de {mes} de %Y")
print(formato_br)
Resultado: 11 de junho de 2025

Isso é feio? Sim. Funciona? Sempre. E você não depende do servidor ter o locale instalado. Primeiro: se você está manipulando datas vindas de usuários brasileiros em formulários web, o padrão DD/MM/YYYY parece inofensivo até receber "02/04/2025" e não saber se é 2 de abril ou 4 de fevereiro. A solução padrão da indústria é usar campos separados de dia, mês e ano, ou forçar o input no formato ISO (YYYY-MM-DD) e exibir formatado apenas na UI. Isso elimina ambiguidade na entrada e deixa a formatação apenas para a camada de apresentação. Segundo: o método toLocaleDateString() do JavaScript com {day: 'numeric', month: 'long', year: 'numeric'} e locale "pt-BR" é a forma mais limpa no frontend. Porém, ele depende do navegador do usuário. Se o navegador estiver configurado para um locale diferente, a data sai errada. Para APIs que precisam garantir o formato independente do cliente, faça a conversão no backend com a lista de meses fixa acima.

Problema comum e quando essa abordagem falha

O maior ponto cego é quando você precisa formatar datas de calendários diferentes — juliano, hebraico, islâmico — ou quando lida com fusos horários e a data muda dependendo de onde o usuário está. A lista fixa de meses em português não resolve isso. Nesses casos, pendulum com a expansão locale="pt_br" é superior porque ele mapeia os nomes corretos internamente sem depender do SO. Também vale notar que nem todo sistema aceita a forma por extenso. Bancos de dados, APIs de terceiros e planilhas muitas vezes esperam 11/06/2025 ou 2025-06-11. Converter para o formato longo é sempre uma decisão de apresentação, nunca de armazenamento. Armazenar sempre em UTC no formato ISO, formatar na hora de mostrar. Isso evita que você tenha que reconverter depois e se pergunte qual foi a data original.