Implementando i18n en Astro | Michelangelo Valderrama

Nuevo artículo, nuevo tutorial.

Aquí una “guía” de como implementar i18n en Astro. ¿Pero no existen ya librerias para eso? Pues sí, pero cuando yo las quise implementar no funcionaban, así que tocó crearse la propia. Además, hacerlo tú mismo te hace menos dependiente de terceros.

Tener una página en muchos idiomas es siempre un fastidio, pero a veces es una necesidad si una quiere que su página web sea más accesible. Pero yo me vi en esta necesidad porque me tocó migrar la web de IF7SPORTS de Angular a Astro. ¿Por qué se usó Angular para una página estática? Ni idea, pero tardaba 6 segundos en cargar y eso no era bueno. En el blog de la web escribí un muy pequeño artículo sobre la migración, os lo dejo aquí. La web también tenía diferentes idiomas, pero se usaba un sistema que yo he denominado sistema de idiomas en base a directorios, donde básicamente tienes una carpeta por cada idioma (aunque el idioma por defecto puede ser la carpeta raíz), llegando a una estructura tal que así:

1
pages/
2
  index.html
3
  en/
4
    index.html
5
  fr/
6
    index.html

De ello aprendí algo muy importante:

Ni de coña vuelvo a tener que copiar una página entera para que esté en otro puto idioma.

Siempre que se añadía cualquier cosa a la web había que realizarlo mínimo dos veces y era horrible, por eso decidí crear el sistema de idiomas de otra manera, uno que he denominado sistema de idiomas en base a archivos, donde tienes las traducciones en archivos separados.

Si quereis basar vuestra sistema de traducción en directorios y comprobar en carne propia por qué es un atentado contra la humanidad os dejo la receta de oficial Astro de cómo hacerlo aquí.

Cosa importante a decir ahora es que todas las rutas tiene el idioma como prefijo, e.g. /en/home o /es/home, por lo que la ruta raiz no es ningún idioma, e.g. /home es un 404, esto puede ser o no importante dependiendo de lo que buscas. Si quieres intentar hacer que la ruta raiz sea el idioma por defecto te deseo buena suerte y que dios te acompañe :>

Configuración y utilidades

Crea el directorio src/i18n, donde estarán todos los scripts y componentes exclusivos de los idiomas, excepto las traducciones.

Cree la carpeta public/locales y dentro de ella, crea un archivo .json por cada idioma que quieras. En mi caso serán el Inglés, Español y Francés.

1
public/
2
  locales/
3
    en.json
4
    es.json
5
    fr.json

En src/i18n/config.ts, añade lo siguiente:

1
import es from '../../public/locales/es.json'
2
import en from '../../public/locales/en.json'
3
import fr from '../../public/locales/fr.json'
4

5
export const LANGUAGES = {
6
  en: 'English',
7
  es: 'Español',
8
  fr: 'Français'
9
}
10

11
export const LOCALES = {
12
  en: 'en-GB',
13
  es: 'es-ES',
14
  fr: 'fr-FR'
15
}
16

17
export const LANGUAGES_ARRAY = Object.keys(LANGUAGES)
18

19
export const DEFAULT_LANGUAGE = 'en'
20

21
export const TRANSLATIONS = { en, es, fr }
22

23
export type Lang = keyof typeof TRANSLATIONS
24
export type Page = keyof (typeof TRANSLATIONS)[typeof DEFAULT_LANGUAGE]

En config.ts se importan las traducciones, se configuran los idiomas, sus locales y se hacen demás cosas útiles.

En el archivo src/i18n/utils.ts, añade lo siguiente:

1
import {
2
  DEFAULT_LANGUAGE,
3
  LANGUAGES,
4
  TRANSLATIONS,
5
  type Lang,
6
  type Page
7
} from './config'
8

9
/**
10
 * Obtiene el idioma por el pathname.
11
 * @param pathname
12
 */
13
export function getLangFromPathname(pathname: string) {
14
  const [, lang] = pathname.split('/')
15
  return lang as Lang
16
}
17

18
/**
19
 * Obtiene el idioma por un objeto URL.
20
 * @param url
21
 */
22
export const getLanguageFromUrl = (url: URL) =>
23
  getLangFromPathname(url.pathname)
24

25
/**
26
 * Configura la función `t` para el idioma indicado.
27
 * @param lang - El idioma deseado.
28
 * @param defaultPage - Indica la página por defecto.
29
 */
30
export function useTranslations(lang: Lang, defaultPage?: Page) {
31
  /**
32
   * Devuelve el texto traducido en la página por defecto o en la especificada.
33
   * @param page - Especifica la página, e.g. `home`, `about`, etc. La clave es de un solo nivel, por tanto `home.title` no es válido.
34
   */
35
  return function t(page?: Page): any {
36
    const lang$ = lang in LANGUAGES ? lang : DEFAULT_LANGUAGE
37
    const page$ = page ?? defaultPage
38

39
    return page$ ? TRANSLATIONS[lang$][page$] : ''
40
  }
41
}

Por último, puedes añadir algunos import aliases útiles a tu archivo tsconfig.json.

1
{
2
  ...,
3
  "compilerOptions": {
4
    "baseUrl": ".",
5
    "paths": {
6
      "@i18n/*": ["src/i18n/*"],
7
      "@layouts/*": ["src/layouts/*"],
8
      "@components/*": ["src/components/*"]
9
    }
10
  }
11
}

Componentes

Para poder cambiar de idioma, crea el archivo src/i18n/LanguagePicker.astro. Yo os dejo dos opciones: un seleccionable o una lista.

1
---
2
import { LANGUAGES, LOCALES, type Lang } from "./config"
3
const url = Astro.url
4
const origin = url.origin
5
const [, lang, ...slug] = url.pathname.split("/")
6
---
7

8
<!-- OPCIÓN 01 -->
9
{
10
  lang in LANGUAGES && (
11
    <select
12
      id="lang-selector"
13
    >
14
      <option value="" disabled selected>
15
        {LANGUAGES[lang as Lang]}
16
      </option>
17
      {Object.entries(LANGUAGES).map(([l, label]) => (
18
        <>
19
          {l !== lang && (
20
            <option value={`${origin}/${l}/${slug.join("/")}`}>
21
              {label}
22
            </option>
23
          )}
24
        </>
25
      ))}
26
    </select>
27
  )
28
}
29

30
<!-- OPCIÓN 02 -->
31
<ul>
32
  {
33
    Object.entries(LANGUAGES).map(([l, label]) => (
34
      <li>
35
        <a
36
          href={`${origin}/${l}/${slug.join("/")}`}
37
          hreflang={LOCALES[l as keyof typeof LOCALES]}
38
        >
39
          {label}
40
        </a>
41
      </li>
42
    ))
43
  }
44
</ul>
45

46
<script>
47
  // solo para la opción 1
48
  function optionsAsLinks(selector: string) {
49
    const selectElem = document.querySelector(selector) as HTMLSelectElement
50
    selectElem.addEventListener("change", () => {
51
      const selectedIndex = selectElem.selectedIndex
52
      if (selectElem.options[selectedIndex].value) {
53
        const url = selectElem.options[selectedIndex].value
54
        window.location = url as string & Location
55
      }
56
    })
57
  }
58
  optionsAsLinks("#lang-selector")
59
</script>

Hay ciertos casos en los que es útil poder establecer etiquetas html invariables a cada idioma sin tener que repetirlo en todos los [language].json, para eso en src/i18n/Trans.astro añade lo siguiente:

1
---
2
import { DEFAULT_LANGUAGE, type Page } from "./config"
3
import { getLanguageFromUrl, useTranslations } from "./utils"
4
import { replaceTextTargetsByTemplate } from "./languageTarget"
5

6
interface Props {
7
  page?: Page
8
  section: string
9
  class?: string
10
}
11

12
const { page, section, class: className } = Astro.props
13
const lang = getLanguageFromUrl(Astro.url)
14
const t = useTranslations(lang, page)
15

16
const slot = await Astro.slots.render("default")
17
const text = lang === DEFAULT_LANGUAGE ? slot : (t()[section] as string)
18
---
19

20
<p class={className} set:html={replaceTextTargetsByTemplate(slot, text)} />

Además, tienes que crear el archivo src/i18n/languageTarget.ts.

1
/**
2
 * Obtiene las etiquetas de un texto HTML.
3
 * @param html
4
 * @returns Retorna un array con las etiquetas, que incluyen `<>` y `</>`.
5
 */
6
function getHtmlTargets(html: string) {
7
  const targets: string[] = []
8
  let index = 0
9
  while (index < html.length) {
10
    if (html[index] === '<') {
11
      const endTarget = html.indexOf('>', index)
12

13
      if (endTarget !== -1) {
14
        const fullTarget = html.slice(index, endTarget + 1)
15
        targets.push(fullTarget)
16
        index = endTarget + 1
17
        continue
18
      }
19
    }
20
    index++
21
  }
22
  return targets
23
}
24

25
/**
26
 * Sustituye las etiquetas numerales (`<0></0>`, `<1></1>`, etc.) de un texto por las etiquetas de una plantilla.
27
 * > El texto y el plantilla han de tener el mismo número de etiquetas.
28
 * @param template
29
 * @param text
30
 */
31
export function replaceTextTargetsByTemplate(template: string, text: string) {
32
  if (!text) throw new Error('Text is undefined')
33

34
  const targets = getHtmlTargets(template)
35
  return text.replace(/<(\d+)>(.*?)<\/\1>/g, (_, pos, cont) => {
36
    const num = parseInt(pos)
37
    return `${targets[num * 2]}${cont}${targets[num * 2 + 1]}`
38
  })
39
}

Para el SEO, crea el archivo src/i18n/I18nHeaders.astro con lo siguiente:

1
---
2
import { DEFAULT_LANGUAGE, LOCALES } from "./config"
3
const [, , ...path] = Astro.url.pathname.split("/")
4
---
5

6
<link
7
  rel="alternate"
8
  href={`${Astro.url.origin}${DEFAULT_LANGUAGE}/${path.join("/")}`}
9
  hreflang="x-default"
10
/>
11
{
12
  Object.keys(LOCALES).map((l) => (
13
    <link
14
      rel="alternate"
15
      href={`${Astro.url.origin}${l}/${path.join("/")}`}
16
      hreflang={LOCALES[l as keyof typeof LOCALES]}
17
    />
18
  ))
19
}
20

21
<meta property="og:locale" content={LOCALES[DEFAULT_LANGUAGE]} />
22
{
23
  Object.keys(LOCALES).map((l) => {
24
    if (l === DEFAULT_LANGUAGE) return
25
    return (
26
      <meta
27
        property="og:locale:alternate"
28
        content={LOCALES[l as keyof typeof LOCALES]}
29
      />
30
    )
31
  })
32
}

Plantillas

Para que el navegador sepa en que idioma se encuentra la página, es importante añadir el atributo lang en la etiqueta html, para ello añade lo siguiente en el archivo src/layouts/BaseLayout.astro:

1
---
2
import I18NHeaders from "@i18n/I18nHeaders.astro"
3
import { getLanguageFromUrl } from "@i18n/utils"
4

5
interface Props {
6
  title: string
7
}
8

9
const lang = getLanguageFromUrl(Astro.url)
10
---
11

12
<html lang={lang}>
13
  <head>
14
    <meta charset="utf-8" />
15
    <meta name="viewport" content="width=device-width" />
16
    <meta name="generator" content={Astro.generator} />
17
    <link rel="shortcut icon" href="/favicon.svg" type="image/x-icon" />
18
    <title>{Astro.props.title}</title>
19
    <I18NHeaders />
20
  </head>
21
  <body>
22
    <slot />
23
  </body>
24
</html>

Páginas

`index.astro`

Como comenté al principio, este sistema no está configurado para que la ruta raiz sea el idioma predeterminado, por lo tanto hay que redirigir al usuario añadiendo lo siguiente en src/pages/index.astro:

1
---
2
import { DEFAULT_LANGUAGE } from "@i18n/config"
3
---
4

5
<meta
6
  http-equiv="refresh"
7
  content={`0;url=/${DEFAULT_LANGUAGE}/`}
8
/>

El problema con esto es que las redirecciones por el lado del cliente son penalizantes para el SEO, por lo que una mejor opción sería usar el modo o hybrid de Astro y cambiar lo anterior por:

1
---
2
import { DEFAULT_LANGUAGE, LANGUAGES } from '@i18n/config'
3
export const prerender = false
4

5
const headers = Object.fromEntries(Astro.request.headers)
6
const userLanguage =
7
  headers['accept-language']?
8
  .split(',')[0]
9
  .split('-')[0]
10
const lang =
11
  userLanguage !== undefined && userLanguage in LANGUAGES
12
  ? userLanguage
13
  : DEFAULT_LANGUAGE
14

15
return Astro.redirect(`/${lang}/`, 301)
16
---

`[lang]`

Las páginas para cada idioma se generan gracias a las rutas dinámicas de Astro, lo único malo es que hay que indicar en todas las páginas los idiomas en los que se va ha traducir.

Crea las traducciones en los [languages].json:

1
{
2
  "home": {
3
    "head_title": "Home",
4
    "title": "Welcome!",
5
    "subtitle": "This is an Astro test with i18n."
6
  }
7
}

1
{
2
  "home": {
3
    "head_title": "Inicio",
4
    "title": "¡Bienvenido!",
5
    "subtitle": "Esto es un prueba de Astro con i18n."
6
  }
7
}

1
{
2
  "home": {
3
    "head_title": "Début",
4
    "title": "Accueillir!",
5
    "subtitle": "Il s'agit d'un test Astro avec i18n."
6
  }
7
}

Crea el directorio src/pages/[lang].

1
pages/
2
  index.astro
3
    [lang]/

En src/pages/[lang]/index.astro añade lo siguiente:

1
---
2
import BaseLayout from "@layouts/BaseLayout.astro"
3
import { LANGUAGES_ARRAY, type Lang } from "@i18n/config"
4
import { useTranslations } from "@i18n/utils"
5

6
export const getStaticPaths = () => {
7
  return LANGUAGES_ARRAY.map((lang) => ({
8
    params: { lang },
9
  }))
10
}
11

12
const { lang } = Astro.params
13
const t = useTranslations(lang as Lang, "home")
14
---
15

16
<BaseLayout title={t().head_title}>
17
  <h1>{t().title}</h1>
18
  <p>{t().subtitle}</p>
19
</BaseLayout>

Ahora deberías poder ejecutar npm run dev y tener una página i18n.

Si quieres ver un ejemplo más completo puedes ir a este repositorio, que tiene un blog y usa traducciones en los componentes.