América Hispânica

Como configurar América Hispânica para seus servidores

Quando você começa a lidar com américa hispânica, a primeira coisa que precisa entender é que não se trata de uma ferramenta que você instala e esquece. É uma configuração de DNS, CDN e regras de redirecionamento que exige teste real antes de ir para produção. Eu passei uma semana entalado com isso em um projeto onde o cliente tinha conteúdo em espanhol brasileiro e português europeu, e os dois precisavam ser servidos a partir do mesmo banco mas com caminhos diferentes. A solução envolvia um bloco de regras no nginx, um wildcard SSL para *.hispamérica.net, e um redirecionamento 301 condicional baseado no Accept-Language do cabeçalho. Nada trivial.

A base do processo é simples de descrever mas chata de executar. Você precisa mapear subdomínios para regiões específicas. O domínio principal pode apontar para o Brasil, enquanto um subdomínio como pt.hispaméricaweb.com serve o público português europeu. Um terceiro, es.hispaméricaweb.com, atende a Espanha e América Latina. Isso parece óbvio quando está no papel, mas na prática você vai encontrar problemas com certificados SSL, cache de browser, e cookies que atravessam domínios indevidamente.

Configuração prática de américa hispânica

O primeiro passo é registrar os domínios e configurar os registros DNS. Você cria um registro A para o domínio principal apontando para o IP do servidor, um CNAME para www redirecionando para o root, e subdomínios separados para cada região. Cada subdomínio precisa de seu próprio certificado SSL se quiser HTTPS puro, ou você pode usar um wildcard *.hispaméricaweb.com que cobre tudo mas exige atenção especial com o SAN (Subject Alternative Name) no certificado. O Let's Encrypt faz isso automaticamente se você usar certbot com o plugin correto. Dentro do nginx, você define um bloco server para cada região. O bloco padrão serve o Brasil. Os outros dois blocos verificam o Accept-Language e fazem um redirecionamento 301 para o subdomínio apropriado. A lógica é: se o navegador enviar pt-PT no header, redireciona para pt.hispaméricaweb.com. Se enviar es-ES ou qualquer outro código espanhol, redireciona para es.hispaméricaweb.com. Qualquer outra coisa fica no Brasil. Isso é fundamental porque usuários brasileiros navegando de Portugal sem alterar o idioma do navegador podem acabar no domínio errado se a lógica não for feita dessa forma.

O truque que eu descobri na marra foi o seguinte: quando você usa redirecionamento 301, o navegador caches permanentemente. Se você errar a regra e mandar um usuário português para o domínio brasileiro, ele vai continuar indo para lá mesmo após você corrigir a configuração. A solução é usar 302 (redirecionamento temporário) durante o período de testes, que é descartado pelo cache do browser, e só mudar para 301 quando tiver certeza absoluta de que as regras estão corretas. Eu perdi dois dias com isso antes de entender o problema. O cache de 301 é extremamente agressivo em Chrome e Firefox, e praticamente impossível de limpar sem abrir uma janela anônima. Um problema que quase ninguém menciona é o wildcard SSL em combinações com CDN como Cloudflare. Quando você usa um certificado wildcard, o Cloudflare precisa ter o modo SSL definido corretamente para que o handshakes funcionem nos três subdomínios. Se estiver em Full Strict, o origin precisa ter certificados válidos para cada subdomínio individualmente, mesmo com o wildcard. A configuração em Full (non-strict) é mais permissiva mas reduz um pouco a segurança. A escolha depende do nível de compliance do seu projeto. Para comércio eletrônico que lida com dados de cartão, Full Strict é obrigatório. Para um blog institucional, Full já resolve.

Aqui vai algo contra-intuitivo que aprendi na prática: a ordem dos blocos server no nginx importa. O bloco com o listen mais específico deve vir antes dos genéricos. Se você colocar o bloco Brasil (sem especificação de domínio no server_name) antes do bloco pt, o nginx vai servir o conteúdo brasileiro para todos os requests que não casarem com um server_name explícito, inclusive os destinados ao domínio português. A ordem correta é: primeiro os subdomínios específicos (pt, es), depois o domínio genérico (principal). Isso é documentado na documentação oficial do nginx mas quase ninguém segue à risca, e o resultado é um comportamento errático que parece bug mas é apenas ordenação de configuração. Outro ponto que requer atenção é o cache de conteúdo entre regiões. Se você usa uma CDN, o cache é compartilhado globalmente por padrão. Isso significa que uma página servida para o Brasil pode ser entregue para um usuário na Espanha se o TTL ainda não tiver expirado. A solução é habilitar o cache por host na CDN, o que isola os caches de cada subdomínio. No Cloudflare, isso é feito com a opção Cache Level definida como "Generate Cache Keys" e excluindo cookies de session dos keys de cache. Sem isso, você vai entregar conteúdo em português brasileiro para usuários espanhóis que esperam receber espanhol da Espanha, e o problema é particularmente visível em páginas com conteúdo dinâmico como preços, promoção e disponibilidade de estoque.

Para quem está começando com américa hispânica, o caminho mais seguro é: configurar os DNS primeiro, testar com 302, validar os certificados SSL com o SSL Labs, colocar em produção com 301 apenas depois de três dias de monitoramento, e manter logs de cada redirecionamento para detectar casos em que a regra de Accept-Language não está funcionando como esperado. Em média, esse processo leva entre 4 e 6 horas para um projeto simples com dois subdomínios e um banco compartilhado, e entre 12 e 18 horas para um setup mais complexo com cache CDN, múltiplas origens, e regras de geolocalização avançadas. Se o projeto tiver mais de cinco regiões, a abordagem de subdomínio puro começa a ficar insustentável. Nesse caso, o caminho alternativo é usar path-based routing (/br/, /pt/, /es/) com o mesmo domínio. A vantagem é um único certificado SSL e configuração mais simples. A desvantagem é que alguns navegadores e políticas de cookie não tratam paths da mesma forma que subdomínios, e o SEO pode sofrer com conteúdo duplicado se as tags canônicas não forem configuradas corretamente. A escolha entre subdomínio e path depende do volume de tráfego, da complexidade do conteúdo, e da estratégia de marketing de cada região. Não existe resposta certa universal.

Como configurar América Hispânica para seus servidores

Quando você começa a lidar com américa hispânica, a primeira coisa que precisa entender é que não se trata de uma ferramenta que você instala e esquece. É uma configuração de DNS, CDN e regras de redirecionamento que exige teste real antes de ir para produção. Eu passei uma semana entalado com isso em um projeto onde o cliente tinha conteúdo em espanhol brasileiro e português europeu, e os dois precisavam ser servidos a partir do mesmo banco mas com caminhos diferentes. A solução envolvia um bloco de regras no nginx, um wildcard SSL para *.hispamérica.net, e um redirecionamento 301 condicional baseado no Accept-Language do cabeçalho. Nada trivial.

A base do processo é simples de descrever mas chata de executar. Você precisa mapear subdomínios para regiões específicas. O domínio principal pode apontar para o Brasil, enquanto um subdomínio como pt.hispaméricaweb.com serve o público português europeu. Um terceiro, es.hispaméricaweb.com, atende a Espanha e América Latina. Isso parece óbvio quando está no papel, mas na prática você vai encontrar problemas com certificados SSL, cache de browser, e cookies que atravessam domínios indevidamente.

Configuração prática de américa hispânica

O primeiro passo é registrar os domínios e configurar os registros DNS. Você cria um registro A para o domínio principal apontando para o IP do servidor, um CNAME para www redirecionando para o root, e subdomínios separados para cada região. Cada subdomínio precisa de seu próprio certificado SSL se quiser HTTPS puro, ou você pode usar um wildcard *.hispaméricaweb.com que cobre tudo mas exige atenção especial com o SAN (Subject Alternative Name) no certificado. O Let's Encrypt faz isso automaticamente se você usar certbot com o plugin correto. Dentro do nginx, você define um bloco server para cada região. O bloco padrão serve o Brasil. Os outros dois blocos verificam o Accept-Language e fazem um redirecionamento 301 para o subdomínio apropriado. A lógica é: se o navegador enviar pt-PT no header, redireciona para pt.hispaméricaweb.com. Se enviar es-ES ou qualquer outro código espanhol, redireciona para es.hispaméricaweb.com. Qualquer outra coisa fica no Brasil. Isso é fundamental porque usuários brasileiros navegando de Portugal sem alterar o idioma do navegador podem acabar no domínio errado se a lógica não for feita dessa forma.

O truque que eu descobri na marra foi o seguinte: quando você usa redirecionamento 301, o navegador caches permanentemente. Se você errar a regra e mandar um usuário português para o domínio brasileiro, ele vai continuar indo para lá mesmo após você corrigir a configuração. A solução é usar 302 (redirecionamento temporário) durante o período de testes, que é descartado pelo cache do browser, e só mudar para 301 quando tiver certeza absoluta de que as regras estão corretas. Eu passei dois dias rastreando um redirecionamento que não queria sair do cache antes de entender o problema. O cache de 301 é extremamente agressivo em Chrome e Firefox, e praticamente impossível de limpar sem abrir uma janela anônima. Um problema que quase ninguém menciona é o wildcard SSL em combinações com CDN como Cloudflare. Quando você usa um certificado wildcard, o Cloudflare precisa ter o modo SSL definido corretamente para que o handshakes funcionem nos três subdomínios. Se estiver em Full Strict, o origin precisa ter certificados válidos para cada subdomínio individualmente, mesmo com o wildcard. A configuração em Full (non-strict) é mais permissiva mas reduz um pouco a segurança. A escolha depende do nível de compliance do seu projeto. Para comércio eletrônico que lida com dados de cartão, Full Strict é obrigatório. Para um blog institucional, Full já resolve.

Aqui vai algo contra-intuitivo que aprendi na prática: a ordem dos blocos server no nginx importa. O bloco com o listen mais específico deve vir antes dos genéricos. Se você colocar o bloco Brasil (sem especificação de domínio no server_name) antes do bloco pt, o nginx vai servir o conteúdo brasileiro para todos os requests que não casarem com um server_name explícito, inclusive os destinados ao domínio português. A ordem correta é: primeiro os subdomínios específicos (pt, es), depois o domínio genérico (principal). Isso é documentado na documentação oficial do nginx mas quase ninguém segue à risca, e o resultado é um comportamento errático que parece bug mas é apenas ordenação de configuração. Outro ponto que requer atenção é o cache de conteúdo entre regiões. Se você usa uma CDN, o cache é compartilhado globalmente por padrão. Isso significa que uma página servida para o Brasil pode ser entregue para um usuário na Espanha se o TTL ainda não tiver expirado. A solução é habilitar o cache por host na CDN, o que isola os caches de cada subdomínio. No Cloudflare, isso é feito com a opção Cache Level definida como "Generate Cache Keys" e excluindo cookies de session dos keys de cache. Sem isso, você vai entregar conteúdo em português brasileiro para usuários espanhóis que esperam receber espanhol da Espanha, e o problema é particularmente visível em páginas com conteúdo dinâmico como preços, promoção e disponibilidade de estoque.

Para quem está começando com américa hispânica, o caminho mais seguro é: configurar os DNS primeiro, testar com 302, validar os certificados SSL com o SSL Labs, colocar em produção com 301 apenas depois de três dias de monitoramento, e manter logs de cada redirecionamento para detectar casos em que a regra de Accept-Language não está funcionando como esperado. Em média, esse processo leva entre 4 e 6 horas para um projeto simples com dois subdomínios e um banco compartilhado, e entre 12 e 18 horas para um setup mais complexo com cache CDN, múltiplas origens, e regras de geolocalização avançadas. Se o projeto tiver mais de cinco regiões, a abordagem de subdomínio puro começa a ficar insustentável. Nesse caso, o caminho alternativo é usar path-based routing (/br/, /pt/, /es/) com o mesmo domínio. A vantagem é um único certificado SSL e configuração mais simples. A desvantagem é que alguns navegadores e políticas de cookie não tratam paths da mesma forma que subdomínios, e o SEO pode sofrer com conteúdo duplicado se as tags canônicas não forem configuradas corretamente. A escolha entre subdomínio e path depende do volume de tráfego, da complexidade do conteúdo, e da estratégia de marketing de cada região. Não existe resposta certa universal.