Astro com subdomínios de idioma

No modo de serviço Subdomínio, o Universally serve cada idioma em seu próprio subdomínio, como fr.example.com, buscando a página de seu domínio principal e traduzindo-a. Seu aplicativo Astro renderiza apenas o idioma de origem. A integração é executada em modo proxy, onde adiciona os links hreflang e o seletor de idioma às suas páginas e nada mais.

Antes de começar

• O projeto está no modo de serviço Subdomínio. Escolha Subdomínio em Como as páginas traduzidas devem ser servidas? quando você o criar. Um projeto no modo JavaScript pode migrar para cá com Mover para subdomínios de idioma em sua página Configuração. Mover um projeto Subdomínio de volta para o SDK ainda não está disponível.
• Acesso ao DNS do seu domínio.
• A função de Proprietário ou Administrador para criar o projeto, e Proprietário, Administrador ou Editor para adicionar nomes de host e clicar em Verificar novamente agora.

Instalar em modo proxy

1. Instale o pacote e adicione UNIVERSALLY_API_KEY a .env, como em Instalar a integração Astro.
2. Registre a integração com mode: 'proxy':

import universally from '@universally-sdk/astro';
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
  integrations: [universally({ mode: 'proxy' })]
});

3. Adicione a tag head uma vez em seu layout, dentro de <head>:

---
import { UniversallyHead } from '@universally-sdk/astro/components';
---

<head>
  <UniversallyHead />
</head>

Definir UNIVERSALLY_MODE=proxy no ambiente faz o mesmo que a opção mode.

Adicionar um subdomínio de idioma

O lado do painel é o mesmo para todos os tipos de projeto e é abordado integralmente em Subdomínios de idioma.

1. Abra Todos os Idiomas. No card Idiomas, clique em Adicionar subdomínio para idioma.
2. Em Adicionar Idioma de Destino, escolha Idioma e Região, depois selecione o formato Subdomínio: Código da Região, Código do Idioma ou Personalizado. O segmento se torna o subdomínio, então Francês com Código do Idioma em example.com se torna fr.example.com. Um www inicial é removido do seu domínio. O nome do host é criado para você.
3. Adicione os três registros DNS mostrados com seu Nome e Valor, em qualquer ordem:

Os registros não devem ser proxy. No Cloudflare, defina Status do proxy como Apenas DNS: um registro com proxy é resolvido como um registro A, que não pode ser validado.

4. Aguarde as verificações. Elas rodam a cada 5 minutos, e a verificação e o certificado levam alguns minutos. Clique em Verificar novamente agora para verificar imediatamente.
5. Reinicie ou reconstrua seu site Astro assim que o subdomínio mostrar Ao vivo. Os nomes de host são lidos quando sua configuração é executada.

O indicador de status exibe Adicionar registros DNS, Verificando, Ativo, DNS movido ou Falha. A linha do tempo passa por DNS adicionado, Domínio verificado, SSL emitido e Ativo. Um nome de host está ativo quando o Cloudflare relata o nome de host e seu certificado como ativos. Para configurações de idioma em geral, consulte Adicionar idiomas.

Qual modo de proxy renderiza

Em https://example.com/about, <UniversallyHead /> renderiza os links de origem e x-default em seu site, e cada destino em seu nome de host com o mesmo caminho:

<link rel="alternate" hreflang="en-us" href="https://example.com/about" />
<link rel="alternate" hreflang="fr" href="https://fr.example.com/about" />
<link rel="alternate" hreflang="x-default" href="https://example.com/about" />

Esses links precisam estar em seu HTML de origem, porque o proxy nunca atende ao seu domínio principal. Consulte tags hreflang. O script do seletor é executado, a menos que switcher: false seja definido.

O modo de proxy ignora todo o resto:

• Sem rotas /fr/. Um caminho de idioma em seu próprio servidor permanece como 404, o que está correto.
• Sem catálogo, relatórios ou sondagens. Seu servidor se comunica com o Universally uma vez, quando a configuração é executada.
• /_universally/revalidate responde com 404.
• t() e href() retornam seu argumento, então um layout escrito para o modo SDK continua funcionando.

Verificar se funcionou

• https://fr.example.com/about carrega sua página em francês.
• A origem de https://example.com/about tem um link para https://fr.example.com/about.

Se não funcionar

• Um idioma está faltando nos links: ele ainda não tem um nome de host ativo. O log diz "...não tem um nome de host ativo no Universally, então foi omitido dos links hreflang." Conclua seus registros DNS, aguarde o status Ativo e, em seguida, reconstrua.
• Os registros não podem ser validados: um registro está em proxy. No Cloudflare, altere-o para Apenas DNS.
• Os links não mudam depois que um subdomínio fica ativo: os nomes de host são lidos quando a configuração é executada. Reinicie ou reconstrua.

Mais casos estão em Solução de problemas de integração do Astro.