3

Estou fazendo a documentação de uma API, mas não sei onde posso encontrar o que define a data nos estilos de formatação brasileiro, italiano, etc, serem do formato dd/mm/yyyy.

Datas no formato yyyy-mm-dd são definidas pela ISO 8601 de 1988. Lá tem todas as explicações sobre formatação, uso etc.

Eu gostaria de saber o que define a data no formato dd/mm/yyyy, que é utilizada em países como Argélia, Brasil, Itália entre outros, para deixar de referência na minha API.

Estou pegando referências como esta resposta do stackoverflow , e também para não ocorrer problemas como este , no qual não se sabe qual o formatação dos campos do tipo data.

De onde eu posso colocar a referência que a data é pra ser usada no formato dd/mm/yyyy?

1

1 Resposta 1

3

Use o formato ISO 8601

Depende muito do que você quer fazer com sua API, mas em geral, um formato de data específico para cada localidade é um problema de apresentação. Internamente o(s) seu(s) sistema(s) deveria(m) trabalhar com algum formato único e independente de localidade, e somente na hora de exibir para o usuário é que você se importaria com a formatação (assumindo que você tem a informação sobre a localização do usuário, para que seja usado o respectivo formato).

Geralmente, a ideia de uma API é ser consumida por outros programas/sistemas, então não invente: use o formato ISO 8601, que é padronizado, não-ambíguo, criado justamente para intercâmbio de informações referentes à datas e horas, e possui suporte da maioria das linguagens e API's (além de ter o aval do W3C, do IETF e por último mas não menos importante, do XKCD).

Se alguém vai enviar dados para a sua API, basta que eles a convertam para o formato ISO 8601 (lembrando que independente do formato escolhido, eles terão que converter de qualquer maneira). Se alguém vai consumir sua API, deixe documentado que elas são retornadas no formato ISO 8601, e esse alguém se vira para exibir a data para seus usuários (não é mais responsabilidade sua a forma como cada consumidor da API exibirá os dados, o importante é você deixar documentado o formato retornado e cada um manipula da forma que achar melhor).


Mas, se quiser usar dd/mm/yyyy...

Não foi explicado o contexto, mas talvez você precise muito que o formato seja "dd/mm/yyyy". Se é assim, sinto informar que é bem difícil ter uma única fonte oficial que sustente ou justifique esta - e qualquer outra - escolha, e mais difícil ainda é encontrar suporte adequado (e consistente) das linguagens e API's para tais fontes (algumas tem mais, outras menos, varia muito).

Nos comentários foi citada a norma ABNT NBR 5892:2019, específica para o formato de datas brasileiro. O documento oficial é pago então não vou colocá-lo na íntegra aqui (sim, eu comprei), mas o único trecho que menciona um formato de data próximo do que você precisa é:

Elementos da data, para dia, mês e ano

Devem ser grafados na seguinte ordem: dia, mês e ano. Quando os elementos forem representados somente por algarismos arábicos, devem ser separados por ponto e sem espaço entre eles.

Ou seja, de acordo com a ABNT, a data de hoje deveria ser escrita como "27.05.2020" (inclusive no próprio documento tem um exemplo: "04.04.2018"). Decepcionante que na prática ninguém siga uma norma oficial, não? Afinal, no dia a dia do Brasil, costumamos usar "27/05/2020" (ou os formatos por extenso, como "27 de maio de 2020", que também são mencionados na norma). De qualquer forma, a norma ABNT não serviria para embasar sua decisão de usar "dd/mm/yyyy".

CLDR

Então vamos à outra fonte: o Unicode Common Locale Data Repository (CLDR). É basicamente um grande repositório de informações relacionadas à localização, incluindo diferentes formatos de data, unidades de medida, formato de números, etc.

Todas essas definições estão espalhadas em vários arquivos, e neles você pode encontrar os diferentes formatos de datas por locale. Mas já adianto que não é tão simples assim.

Por exemplo, no arquivo referente ao português de Portugal, temos:

<dateFormatLength type="medium">
    <dateFormat>
        <pattern>dd/MM/y</pattern>
    </dateFormat>
</dateFormatLength>
<dateFormatLength type="short">
    <dateFormat>
        <pattern draft="contributed">dd/MM/yy</pattern>
    </dateFormat>
</dateFormatLength>

Já no arquivo referente ao português do Brasil, não há tais definições, então ele deve usar a definição do arquivo genérico do idioma português, que tem o seguinte:

<dateFormatLength type="medium">
    <dateFormat>
        <pattern>d 'de' MMM 'de' y</pattern>
    </dateFormat>
</dateFormatLength>
<dateFormatLength type="short">
    <dateFormat>
        <pattern>dd/MM/y</pattern>
    </dateFormat>
</dateFormatLength>

Os arquivos citados acima foram consultados em 27 de maio de 2020.

No mesmo repositório você vai encontrar arquivos para vários locales diferentes, como por exemplo o italiano e o argelino.

Sendo assim, então qual o formato "brasileiro" de fato? E os formatos "português", "italiano" ou "argelino"? Bom, depende da linguagem utilizada. Por exemplo, em JavaScript:

let d = new Date('2020-05-27T00:00');
[
 'pt-BR', // Brasil
 'pt-PT', // Portugal
 'it-IT', // Itália
 'ar-DZ'  // Argélia
].forEach(locale => console.log(locale, d.toLocaleDateString(locale)));

Testando no Chrome, a saída foi:

pt-BR 27/05/2020
pt-PT 27/05/2020
it-IT 27/5/2020
ar-DZ 272020/5/

Também testei localmente rodando no Node (sem ter os locales instalados) e todas retornaram "2020-5-27".

Já usando Java (API java.time, disponível para JDK >= 8):

static void printDate(Locale locale) {
    System.out.println("Locale: " + locale);
    for (FormatStyle style : Arrays.asList(FormatStyle.MEDIUM, FormatStyle.SHORT)) {
        DateTimeFormatter formatter = DateTimeFormatter.ofLocalizedDate(style).withLocale(locale);
        System.out.printf("%7s %s\n", style, formatter.format(LocalDate.now()));
    }
}

printDate(new Locale("pt", "BR"));
printDate(new Locale("pt", "PT"));
printDate(new Locale("ar", "DZ"));
printDate(new Locale("it", "IT"));

A saída varia conforme a versão. No Java 8 foi:

Locale: pt_BR
 MEDIUM 27/05/2020
  SHORT 27/05/20
Locale: pt_PT
 MEDIUM 27/mai/2020
  SHORT 27-05-2020
Locale: ar_DZ
 MEDIUM 27/05/2020
  SHORT 27/05/20
Locale: it_IT
 MEDIUM 27-mag-2020
  SHORT 27/05/20

No Java 9:

Locale: pt_BR
 MEDIUM 27 de mai de 2020
  SHORT 27/05/20
Locale: pt_PT
 MEDIUM 27/05/2020
  SHORT 27/05/20
Locale: ar_DZ
 MEDIUM 27?/05?/2020
  SHORT 27?/5?/2020
Locale: it_IT
 MEDIUM 27 mag 2020
  SHORT 27/05/20

E no Java 13:

Locale: pt_BR
 MEDIUM 27 de mai de 2020
  SHORT 27/05/2020
Locale: pt_PT
 MEDIUM 27/05/2020
  SHORT 27/05/20
Locale: ar_DZ
 MEDIUM 27?/05?/2020
  SHORT 27?/5?/2020
Locale: it_IT
 MEDIUM 27 mag 2020
  SHORT 27/05/20

Ou seja, se eu quisesse a data como "27/05/2020" e estivesse usando o locale pt_BR, no Java 8 deveria usar o formato "MEDIUM", no Java 13 o formato "SHORT" e no Java 9 eu teria que mudar o locale para pt_PT (ou eu simplesmente desisto de usar o locale e uso o formato fixo "dd/MM/yyyy"). Essa inconsistência se deve principalmente ao fato de que a partir do JDK 8 o Java passou a seguir o CLDR, mas isso só passou a ser a opção default a partir do JDK 9. E a cada versão tem mais atualizações (que também podem acompanhar eventuais mudanças nas próprias definições do CLDR), ocasionando essas diferenças (exemplo).

As interrogações que aparecem para o locale ar_DZ (Argélia) correspondem ao caractere "RIGHT-TO-LEFT MARK", que basicamente serve para indicar que o texto em questão é escrito da direita para a esquerda. É por isso que no JavaScript eu obtive "272020/5/" (o browser renderizou corretamente, já no Java eu usei um terminal que não suporta a renderização da direita para a esquerda). Mas repare que este caractere só foi incluído a partir do Java 9.

Se quiser, veja este código rodando no IdeOne.com (Java 12), e repare que o browser renderiza corretamente o RIGHT-TO-LEFT MARK.

Apenas para citar mais um exemplo, fiz um teste em Python 3.7 (lembrando que os locales devem estar instalados no sistema, conforme explicado aqui):

import locale
from datetime import datetime

d = datetime(2020, 5, 27)
for loc in ['pt_BR', 'pt_PT', 'it_IT', 'ar_DZ']:
    locale.setlocale(locale.LC_ALL, f'{loc}.utf8')
    print(loc, d.strftime('%x'))

A saída foi:

pt_BR 27/05/2020
pt_PT 27/05/2020
it_IT 27/05/2020
ar_DZ 27-05-2020

Conclusão

Mesmo que exista uma fonte "oficial" como o CLDR, o suporte das diferentes linguagens e API's varia muito: elas podem seguir total ou parcialmente, ou então usar implementações próprias que podem ou não coincidir com a definição do CLDR (e o próprio CLDR tem seu cronograma de lançamento de novas versões, que podem alterar essas definições). Se sua API depender destas definições, vai ser complicado justificar qualquer escolha de formato que seja (e se não quiser ter o problema da inconsistência entre as linguagens, você terá que implementar essas regras, o que na minha opinião é trabalhoso demais para valer a pena - valeria se fosse uma API específica de internacionalização/localização, pois aí o core dela seria a implementação de tais regras).

E mesmo que você decida não usar o CLDR e verifique se existe uma norma para cada país, ainda há a questão cultural, que pode não ser compatível com as normativas, como vimos no caso da ABNT.

Por isso eu iria pela sugestão inicial, de usar o formato ISO 8601, que já é uma norma "internacional" e mais abrangente, em vez de procurar normas locais para cada lugar. E deixe a conversão para outros formatos apenas para fins de apresentação, caso seja pertinente.

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .