Instalar la integración de Astro

La instalación consta de cuatro pasos: agregar el paquete, poner tu clave API en .env, registrar la integración en astro.config.mjs y agregar un componente a tu layout. Después de eso, cada página que ya tengas también se servirá bajo el prefijo de cada idioma, como /fr/about.

Antes de empezar

• Astro 5 o superior, con output: 'server' o output: 'static'. La renderización del lado del servidor también requiere un adaptador de Astro.
• Node 18 o superior. Leer .env y .env.local requiere Node 20.12 o superior. En versiones anteriores de Node, los archivos se omiten sin error, así que configura UNIVERSALLY_API_KEY en el entorno de proceso en su lugar.
• El rol de Propietario o Administrador en el espacio de trabajo, para crear el proyecto y ver su clave API. Los Editores verán "Pide al administrador del proyecto la clave API de este proyecto" en lugar de la clave.

Crear el proyecto

1. Inicia un nuevo proyecto. En Selecciona tu tecnología, elige Astro (marcado como Beta).
2. Completa Dominio, el dominio completo donde se sirve el sitio. Es obligatorio para Astro.
3. Completa Nombre del proyecto, verifica Idioma de origen (Inglés (EE. UU.) por defecto) y haz clic en Siguiente.
4. En Instrucciones de configuración, elige SDK en ¿Cómo se deben servir las páginas traducidas? y haz clic en Continuar.

La pantalla luego enumera los cuatro pasos de instalación a continuación, con un contador "{n} de 4 completados". Cada paso tiene un botón Marcar como completado. Las marcas se almacenan solo en tu navegador y no bloquean nada. Los mismos pasos permanecen disponibles más tarde en Configuración en la barra lateral del proyecto.

1. Instala la integración

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

2. Agrega tu clave API

Coloca la línea de la página de Configuración en .env, junto a tus otros secretos, en la raíz del proyecto Astro:

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

La clave es una cadena de 64 caracteres. Mantenla en el servidor y nunca subas .env a un repositorio. La misma clave está en Configuración de API detrás de Mostrar clave API. Consulta Encontrar tu clave API.

3. Configura Astro

Registra la integración en astro.config.mjs y configura site a tu dominio:

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() lee la clave de .env, así que no le pases nada. site es obligatorio para los enlaces hreflang, ya que deben ser URLs absolutas. Un sitio estático omite el adaptador y usa output: 'static'. Todas las opciones se enumeran en Opciones de integración de Astro.

Para tipificar Astro.locals, agrega dos líneas a src/env.d.ts:

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

4. Úsalo en tus páginas

Agrega la etiqueta head una vez en tu layout, luego traduce cadenas con t(). Este es 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 /> no recibe props. Renderiza los enlaces hreflang y el script del selector de idioma. Luego, envuelve el texto de una página, aquí 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>

Un archivo de página sirve para todos los idiomas. Traducir páginas en Astro cubre t(), href(), HTML en línea e islas.

Añadir idiomas

1. Haz clic en Continuar a los idiomas.
2. En Añadir idiomas, agrega al menos un idioma de destino. Su Formato de URL decide el prefijo: Código de idioma (el predeterminado) da /fr/, Código de región usa la región, por lo que Español (México) se convierte en /mx/, y Personalizado toma de 2 a 6 caracteres. Ver Añadir idiomas.
3. Haz clic en Finalizar. Permanece deshabilitado hasta que el proyecto tenga un idioma.

Los idiomas se leen cuando se ejecuta la configuración de Astro. Reinicia el servidor de desarrollo después de añadir uno.

Verificar que funcionó

npx astro dev

Abre http://localhost:4321/about para tu texto de origen y http://localhost:4321/fr/about para francés. La primera renderización de una cadena nueva muestra el texto de origen. Recarga después de uno o dos segundos y se traducirá. Ve el código fuente de la página para confirmar un <link rel="alternate" hreflang> por idioma.

Si no funciona

• La compilación falla con "set UNIVERSALLY_API_KEY in .env…": la clave no está en las opciones, el entorno, .env.local, o .env junto a astro.config.mjs.
• /fr/about devuelve 404: el idioma se añadió después de que el servidor de desarrollo se iniciara, o su interruptor En vivo está desactivado. Reinicia.
• No hay enlaces hreflang: falta site en astro.config.mjs.

Hay más casos en Solución de problemas de integración de Astro.