Instalar a integração com Astro

A instalação leva quatro etapas: adicione o pacote, coloque sua chave de API em .env, registre a integração em astro.config.mjs e adicione um componente ao seu layout. Depois disso, todas as páginas que você já tem também são servidas sob o prefixo de cada idioma, como /fr/about.

Antes de começar

• Astro 5 ou mais recente, com output: 'server' ou output: 'static'. A renderização do lado do servidor também precisa de um adaptador Astro.
• Node 18 ou mais recente. A leitura de .env e .env.local requer Node 20.12 ou mais recente. Em versões mais antigas do Node, os arquivos são ignorados sem erro, então defina UNIVERSALLY_API_KEY no ambiente de processo em vez disso.
• A função Proprietário ou Administrador no espaço de trabalho, para criar o projeto e ver sua chave de API. Editores veem "Peça a um administrador do projeto a chave de API deste projeto." em vez da chave.

Criar o projeto

1. Inicie um novo projeto. Em Selecione Sua Tecnologia, escolha Astro (marcado como Beta).
2. Preencha Domínio, o domínio totalmente qualificado onde o site é servido. É obrigatório para Astro.
3. Preencha Nome do Projeto, verifique Idioma de Origem (Inglês (EUA) por padrão) e clique em Avançar.
4. Em Instruções de Configuração, escolha SDK em Como as páginas traduzidas devem ser servidas? e clique em Continuar.

A tela então lista as quatro etapas de instalação abaixo, com um contador "{n} de 4 concluídas". Cada etapa tem um botão Marcar como concluída. As marcas são armazenadas apenas no seu navegador e não bloqueiam nada. As mesmas etapas permanecem disponíveis mais tarde em Configuração na barra lateral do projeto.

1. Instale a integração

npm install @universally-sdk/astro
# or: pnpm add @universally-sdk/astro
# or: yarn add @universally-sdk/astro
# or: bun add @universally-sdk/astro

2. Adicione sua chave de API

Coloque a linha da página de Configuração em .env, ao lado de seus outros segredos, na raiz do projeto Astro:

UNIVERSALLY_API_KEY=paste-the-64-character-key-here

A chave é uma string de 64 caracteres. Mantenha-a no servidor e nunca envie .env. A mesma chave está em Configurações de API atrás de Mostrar chave de API. Veja Encontre sua chave de API.

3. Configure o Astro

Registre a integração em astro.config.mjs e defina site para o seu domínio:

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

export default defineConfig({
  site: 'https://example.com',
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [universally()]
});

universally() lê a chave de .env, então você não passa nada para ela. site é necessário para links hreflang, pois eles precisam ser URLs absolutos. Um site estático descarta o adaptador e usa output: 'static'. Todas as opções estão listadas em Opções de integração do Astro.

Para tipar Astro.locals, adicione duas linhas a src/env.d.ts:

/// <reference types="astro/client" />
/// <reference types="@universally-sdk/astro/env" />

4. Use em suas páginas

Adicione a tag head uma vez em seu layout, depois traduza strings com t(). Este é src/layouts/Base.astro:

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

const { t } = Astro.locals;
---

<html lang={Astro.currentLocale}>
  <head>
    <meta charset="utf-8" />
    <title>{t('My site')}</title>
    <UniversallyHead />
  </head>
  <body>
    <slot />
  </body>
</html>

<UniversallyHead /> não recebe props. Ele renderiza os links hreflang e o script do seletor de idioma. Em seguida, envolva o texto de uma página, aqui src/pages/about.astro:

---
import Base from '../layouts/Base.astro';

const { t, href } = Astro.locals;
---

<Base>
  <h1>{t('About us')}</h1>
  <p><a href={href('/pricing')}>{t('See pricing')}</a></p>
</Base>

Um arquivo de página atende a todos os idiomas. Traduzir páginas em Astro cobre t(), href(), HTML inline e ilhas.

Adicionar idiomas

1. Clique em Continuar para idiomas.
2. Em Adicionar idiomas, adicione pelo menos um idioma de destino. Seu Formato de URL decide o prefixo: Código do idioma (o padrão) resulta em /fr/, Código da região usa a região, então Espanhol (México) se torna /mx/, e Personalizado aceita de 2 a 6 caracteres. Veja Adicionar idiomas.
3. Clique em Concluir. Ele permanece desativado até que o projeto tenha um idioma.

Os idiomas são lidos quando sua configuração do Astro é executada. Reinicie o servidor de desenvolvimento após adicionar um.

Verificar se funcionou

npx astro dev

Abra http://localhost:4321/about para seu texto de origem e http://localhost:4321/fr/about para francês. A primeira renderização de uma nova string mostra o texto de origem. Recarregue após um ou dois segundos e ela será traduzida. Visualize o código-fonte da página para confirmar um <link rel="alternate" hreflang> por idioma.

Se não funcionar

• A compilação falha com "set UNIVERSALLY_API_KEY in .env…": a chave não está nas opções, no ambiente, em .env.local ou em .env ao lado de astro.config.mjs.
• /fr/about retorna 404: o idioma foi adicionado após o servidor de desenvolvimento ter sido iniciado, ou seu seletor Ao vivo está desativado. Reinicie.
• Sem links hreflang: site está faltando em astro.config.mjs.

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