Um formulário de endereço que funciona para um país costuma ser um formulário que funciona para o país de quem o escreveu. No momento em que um segundo país entra em cena, as suposições sobre quantidade de linhas, ordem dos campos, posição do código postal e conjunto de caracteres começam a colidir. E as falhas raramente aparecem como travamento: são endereços que salvam sem erro e não podem receber uma entrega. Este texto reúne o que de fato muda entre países e os pontos em que um formulário internacional costuma quebrar.
Por que um formulário que funciona em um país falha no segundo
Um formulário nasce de um exemplo concreto. Quem escreve o código tem em mente uma rua, uma cidade, um código postal com um formato conhecido e um telefone com um comprimento previsível. Todas essas escolhas viram regras: quantas linhas de texto livre existem, qual campo é obrigatório, qual expressão regular aceita o código postal, qual transformação é aplicada antes de gravar.
Enquanto o produto atende um único país, essas regras descrevem a realidade. Quando o seletor de país é adicionado, elas continuam valendo para todos os países ao mesmo tempo, e é aí que a suposição se transforma em defeito. O caso mais comum não é o campo que rejeita algo: é o campo que aceita, grava e não reclama. Um endereço com formato plausível e conteúdo geograficamente impossível passa por qualquer verificação que olhe um campo de cada vez, e só é descoberto quando uma transportadora, um motor de impostos ou um serviço de limpeza de endereços cruza os campos entre si.
Vale separar duas perguntas que parecem a mesma coisa e não são. A primeira é se o dado tem o formato do país. A segunda é se os campos do registro concordam entre si. A maior parte dos formulários testa a primeira e nunca testa a segunda, e é na segunda que mora o defeito caro.
Ordem e quantidade de linhas do endereço
Endereços ocidentais são escritos do menor para o maior: nome, rua, cidade, divisão, código postal, país. Endereços japoneses, chineses e coreanos seguem o caminho inverso: país, província ou prefeitura, cidade, distrito, e só então rua e edifício. Um formulário que renderiza um modelo fixo de linha de endereço, cidade, divisão e código postal e depois tenta encaixar um endereço japonês ali dentro produz algo que lê errado para uma pessoa, mesmo com todos os campos preenchidos corretamente.
A quantidade de linhas também varia. Um endereço britânico costuma precisar de quatro ou cinco linhas, incluindo a cidade de entrega. Um endereço americano normalmente cabe em três. Um endereço japonês frequentemente precisa de duas linhas só para o quarteirão e o número do edifício. Duas linhas gerais de endereço formam o mínimo defensável; uma não é suficiente; quatro são generosidade, não exagero.
O rótulo da camada intermediária também não é estado em todo lugar. É província, região, prefeitura, oblast, governadoria, emirado, departamento ou condado, dependendo de onde você está. O rótulo importa menos do que permitir que o campo seja opcional onde o país não usa essa camada no endereçamento postal. A comparação entre as convenções de escrita está detalhada em formato de endereço internacional, e os códigos que representam cada divisão de forma estável aparecem em códigos de país e subdivisão.
Onde fica o código postal e qual é o padrão de cada país?
A posição do código postal no endereço renderizado muda conforme o país. Alemanha, França, Japão e Coreia colocam o código antes da cidade. Estados Unidos, Reino Unido, Canadá e Austrália colocam depois. O código irlandês é alfanumérico e não ocupa o mesmo espaço de um código numérico. Em vários lugares não existe sistema de código postal em uso no dia a dia, então o campo precisa ser opcional e não obrigatório.
Os padrões também diferem, e não são todos numéricos. O Reino Unido mistura letras e dígitos com um espaço interno que carrega significado. Os Países Baixos usam quatro dígitos seguidos de duas letras. O Canadá alterna letra e dígito. O Japão usa três dígitos, um hífen e mais quatro dígitos. A Alemanha usa cinco dígitos. Uma regra de cinco caracteres numéricos é uma regra americana usando um nome global, e é o defeito mais frequente em formulários que tentaram ser internacionais. O panorama completo está em formatos de código postal por país.
Limites de comprimento são o mesmo bug em outra roupa. Um postcode britânico, com o espaço interno, precisa de mais caracteres do que um campo curto costuma oferecer, então um máximo pequeno demais corrompe um endereço válido em silêncio. Dimensionar o campo pelo código mais curto que um país emite é o mesmo erro na direção oposta, e truncar é pior do que rejeitar, porque o formulário informa sucesso.
O que o código postal informa além do formato?
Um código postal não é apenas uma sequência que casa com um formato: é o endereço de uma área de entrega, e os caracteres iniciais carregam geografia na maioria dos sistemas. Nos Estados Unidos o primeiro dígito de um código postal identifica um grupo de estados. No Canadá o primeiro caractere da área de triagem nomeia uma província ou território. No Reino Unido a parte anterior ao espaço nomeia uma área postal e um distrito, o que restringe a localidade à qual o código pode pertencer. Na Alemanha os dois primeiros dígitos identificam uma região.
Um formulário que confere só o formato joga toda essa informação fora: um código de uma região passa como se fosse de outra, e os dois passam em silêncio até alguém consultar o endereço de verdade.
A validação de código postal tem, portanto, dois níveis. O primeiro é o formato, que pega erro de digitação. O segundo é a relação entre código e localidade, que exige dados de referência embarcados junto com o código. Teste os dois. Se só puder testar um, teste a relação, porque uma falha de formato é visível para quem preenche, enquanto um código com formato válido no lugar errado não é visível para ninguém.
Telefone, prefixo de discagem e quantidade de dígitos
Números de telefone entram nesta conversa porque formulários de endereço costumam coletá-los no mesmo bloco. Duas coisas mudam de país para país: o prefixo nacional de discagem e o comprimento do número depois que esse prefixo é removido.
O prefixo de discagem é o dígito inicial usado para ligações domésticas, frequentemente zero. O formato internacional o omite, então um formulário que armazena a entrada exatamente como veio e depois prefixa o código do país produz números que não podem ser discados. O padrão seguro é aceitar a entrada nacional, remover o prefixo de discagem quando ele estiver presente e guardar o resultado em formato internacional.
O comprimento também não é uniforme, e a validação deve consultar o registro do país em vez de assumir uma regra global única. O código do país é a terceira variável: um seletor que troca o código de discagem sem trocar o comprimento nacional esperado vai aceitar um número com a quantidade errada de dígitos para aquele país. Mantenha o código derivado do país selecionado e valide o número nacional por conta própria.
Concatenação de endereços latinos e CJK
É aqui que a maioria dos formulários internacionais desiste em silêncio. Endereços CJK são concatenados sem espaços entre as camadas administrativas, e as camadas vão do maior para o menor. O mesmo endereço romanizado vai do menor para o maior e ganha espaços. Se um formulário junta os campos com vírgula e espaço e exibe o resultado em uma linha só, as duas versões saem erradas.
A largura dos caracteres adiciona outra falha. Dígitos e letras digitados em um teclado japonês ou chinês podem vir em largura total, e a largura total não é o mesmo caractere que a forma comum, mesmo quando as duas parecem idênticas na tela. Nomes podem ser escritos com o sobrenome primeiro, o que quebra qualquer divisão entre nome e sobrenome seguida de uma recombinação na ordem oposta. E a quebra de linha dentro de texto CJK não tem espaços para quebrar, então um contêiner de largura fixa pode transbordar em vez de quebrar a linha.
Se o seu produto é vendido no Japão, na Coreia, na China ou em Taiwan, teste com strings CJK reais e não com transliterações. Um formulário que lida bem com um nome romanizado não é evidência de que lida com os caracteres que a pessoa vai realmente digitar. A página do Japão mostra como os campos de um país com escrita própria se organizam.
Quais entradas quebram um validador ingênuo?
Três classes de entrada quebram validadores ingênuos, e nenhuma delas é exótica.
Caracteres de largura total. Um método de entrada japonês ou chinês produz dígitos e letras latinas em largura total. A forma de largura total do algarismo um parece quase idêntica na tela e não é um dígito para um analisador, então a pessoa pode digitar um código postal que se lê corretamente e ver o formulário rejeitá-lo. Normalize com a forma de compatibilidade Unicode antes de validar o valor armazenado.
Acentos e letras especiais. Endereços alemães contêm caracteres próprios, nomes nórdicos contêm letras adicionais, o turco tem o i sem ponto, e o vietnamita empilha marcas de tom. Um limite de caracteres conta de um jeito diferente de uma coluna de banco de dados medida em bytes depois que o texto está em UTF-8, e uma romanização bem-intencionada reescreve um nome que a pessoa digitou, o que é um defeito de qualidade de dados mesmo quando não é um erro de validação.
Ordem dos nomes e tratamento. Nomes húngaros, japoneses, chineses e coreanos são comumente escritos com o sobrenome primeiro, boa parte da América Latina usa dois sobrenomes, e tratamentos fazem parte do bloco de endereço em vez de serem decoração. Um par nome e sobrenome não consegue representar um nome que não se divide assim, e uma recombinação que assume a ordem ocidental imprime um nome japonês na ordem inversa.
Teste as três com strings reais, no alfabeto real, em vez de uma transliteração.
Passagem manual de teste em três países
Verificações automatizadas pegam regressões; uma passagem manual pega suposições. Vinte minutos entre Estados Unidos e Alemanha revelam mais do que uma semana de testes unitários escritos por quem escreveu o formulário, porque esses dois países discordam em quase todos os eixos, e o Brasil acrescenta um terceiro conjunto de suposições.
- Estados Unidos. Código postal depois da cidade, sigla de estado com duas letras, cinco dígitos com extensão opcional. Confira que o campo aceita entrada simples e com hífen e que a segunda linha é honestamente opcional.
- Alemanha. Código postal antes da cidade, sem letras, e um estado federado que quase ninguém digita porque o código já o implica. Confira que um campo de estado obrigatório não vira beco sem saída e que uma rua com caractere especial sobrevive ao trajeto.
- Brasil. Código de oito dígitos escrito com hífen, sigla de estado com duas letras e endereços que quase sempre precisam de um campo de bairro que muitos modelos não têm. Confira que o bairro tem para onde ir.
Depois faça as mesmas cinco coisas para cada país: insira um exemplo válido e confirme que ele salva; insira um código postal de outra região e veja se algo reclama; cole um endereço inteiro na primeira linha e observe o que acontece; troque o seletor de país depois de digitar e veja o que o formulário limpa; recarregue o registro salvo e compare com o que foi digitado. Repita uma vez na largura de um celular, porque metade dessas falhas só aparece quando o layout colapsa.
Onde os formulários internacionais costumam quebrar
| Ponto | O que costuma acontecer | Sinal no teste |
|---|---|---|
| Campo de região | Obrigatório para todos os países, inclusive os que não usam a camada | Usuário de país sem região não consegue concluir |
| Formato do código postal | Fixado em cinco dígitos, com máximo que trunca | Código válido mais longo é salvo cortado |
| Transformação de caixa | Maiúsculas forçadas em código sensível a caixa | Valor exibido difere do valor salvo |
| Seletor de país | Sem busca e posicionado depois dos campos de endereço | Pessoa preenche na ordem errada |
| Dicas de autocompletar | Não correspondem ao significado real do campo | Navegador coloca a rua no campo da cidade |
| Segunda linha | Rotulada como complemento, mas é o único lugar do número CJK | Endereço japonês não tem onde caber |
| Placeholders | Usados como rótulo | A dica de formato desaparece ao digitar |
| Divisões longas | Falta de espaço para nomes longos | Nome de província é cortado na exibição |
| Colagem | Endereço completo colado fica parado na primeira linha | Formulário não oferece caminho de colar e interpretar |
Um checklist para rodar antes de publicar
Ordene o checklist por risco, não por campo. Precisa testar em toda versão: um exemplo válido e um inválido por país suportado; a obrigatoriedade que acompanha o país, especialmente um código postal que continua opcional onde não existe sistema; cada campo de texto livre contra o valor realista mais longo; e uma ida e volta de salvar e recarregar.
Armadilhas comuns: um formato de código postal fixo, uma transformação para maiúsculas que corrompe um código sensível a caixa, e um campo de região obrigatório onde o país não tem um.
Fácil de passar batido: verificações numéricas que rejeitam dígitos de largura total, validação que roda antes da normalização, regras de front-end e back-end que discordam, e mensagens de erro que nomeiam o campo mas não o motivo. Essa terceira camada encontra os defeitos interessantes, porque nada disso quebra a compilação. O detalhamento de onde cada verificação deve ficar aparece em validação e normalização de endereço.
Depois verifique o layout, não só o validador: ordem dos campos, texto dos rótulos, opcionalidade e comprimentos máximos precisam ser conferidos por país, porque é isso que a pessoa encontra na tela. Guarde um instantâneo do formulário renderizado para um conjunto representativo de países, assim uma regressão de layout fica visível na revisão.
Gere os exemplos em vez de digitá-los à mão. O gerador de endereços devolve o mesmo registro para a mesma chave, o que mantém um instantâneo estável entre execuções. Os exemplos produzidos são sintéticos e servem apenas para teste de software: não descrevem nenhum imóvel, nenhuma pessoa e nenhum destinatário real, e não podem ser usados para postar nada nem para comprovar residência. Exemplos digitados à mão sofrem desvio, e o desvio é invisível até uma mudança no formulário quebrá-los.
Próximos passos
Escolha três países com convenções bem diferentes — um do Leste Asiático, um europeu e um das Américas — e percorra o checklist acima em cada um deles. Comece pelos dois casos que mais geram reclamação de suporte: país sem código postal obrigatório e perda de dados ao trocar o seletor de país. Se precisar de material de partida, gere um endereço por país no gerador de endereços e compare as linhas antes de escrever as regras de validação. E transforme a passagem manual em uma bateria automatizada que rode a cada alteração no formulário, para que a suposição que você acabou de corrigir não volte pela porta dos fundos.