RFC: Add internationalization

Este PR es un RFC (Request for comments) para añadir la internacionalización en el portafolio. En el cual estoy proponiendo la librería @astrolicious/i18n para manejar la internacionalización en Astro.

Cambios Realizados

Para poder utilizar la librería se debió actualizar la estructura del proyecto:

Se creó la carpeta routes que contiene las rutas que manejará la librería para la internacionalización.
Se creó la carperta locales que contendrá la información requerida para cada lenguaje.

Funcionamiento de la libería

En el archivo astro.config.ts se añadió la configuración de la librería:

// ...
integrations: [
  i18n({
    defaultLocale: 'es',
    locales: ['es', 'en'],
    pages: {
      '/sobre-mi': {
        en: '/about-me',
      },
      '/planograma': {
        en: '/planogramm',
      },
    },
  }),
],
// ...

Donde se establece el idioma por defecto con la propiedad defaultLocale y los idiomas soportados con locales, en la propiedad pages se maneja la internacionalización de las rutas. Referencia: https://astro-i18n.netlify.app/usage/configuration/.

Configurar el cambio de idioma

Para configurar el cambio de idioma, la librería ofrece el método switchLocalePath que permite alternar en cada idioma configurado. Este método es utilizado en el componente LanguageToggle.astro.

Añadiendo internacionalización

Para añadir la internacionalización se debe hacer dentro de la carpeta locales, donde dentro se debe tener una carpeta para cada idioma (Referencia), luego en el archivo common.json se debe añadir en forma de clave: valor la propiedad y el valor que tendrá para dicho idioma. Para esto se eligió la sintaxis de snake_case.

Utilizando la internacionalización

Para utilizar la traducción que añadimos la librería ofrece el método t, el cual por debajo utiliza la librería i18next.

Ejemplo de referencia de uso:

---
import { t } from 'i18n:astro';
---

<h1>{t('hero_title')}</h1>

Cuando es necesario añadir HTML en la información, se puede hacer de la siguiente manera:

{
  "hero_subtitle": "Una <span class=\"highlighted-role\">UX Senior</span> con alma de Junior",
}

Y para utilizarlo en Astro se puede usar la directiva set:html. Se puede hacer de 2 maneras:

Utilizando la directiva directamente en el elemento:

<p class="hero-description" set:html={t('hero_subtitle')} />

Utilizando el componente Fragment:

<p class="hero-description">
  <Fragment set:html={t('hero_subtitle')} />
</p>

Se puede utilizar cualquiera de las 2 maneras, en este caso se utilizó el componente <Fragment /> para mayor legibilidad.

Manejar la internacionalización de rutas

Para que la librería pueda dirigirnos a la ruta especifica se debe utilizar el método getLocalePath, esto actualizará la ruta de los enlaces al cambiar de idioma. Se puede encontrar un ejemplo en el archivo Navbar.astro.

Ventajas

Está librería permite que la internacinalización se maneje de manera estática, lo que al hacer build del proyecto se crea la carpeta /en conteniendo la versión en inglés del proyecto, lo que evita hacer uso de JavaScript y favorecerá en cuanto a SEO.

Además no es necesaria la duplicación de código o de componentes, ya que al utilizar los métodos proporcionados por la librería, los cambios realizados en el código se verán reflejados para ambos idiomas directamente.

Limitaciones

Si bien es posible añadir HTML en los archivos de internacionalización como por ejemplo:

{
  "hero_subtitle": "Una <span class=\"highlighted-role\">UX Senior</span> con alma de Junior",
}

La limitante en este caso es añadir estilos CSS a elementos que vienen directamente de los archivos JSON, Astro al utilizar una estrategía para los estilos, estos no pueden ser aplicados. La solución para esto, es utilizar las hojas de estilos de SASS localizados en la carpeta styles, para la clase .highlighted-role se añadieron los estilos en src/styles/base/_general.scss

Vista previa de funcionamiento

https://github.com/AnaRangel/anarangel.github.io/assets/38303370/46b3dc05-3043-43a8-b83c-213aa85e1033

Por favor revisar la PR y dejar cualquier duda al respecto. En caso de valorar de manera positiva la forma de uso de la librería pueden hacer merge de la PR ya que la configuración inicial ya está realizada, lo único que se debe hacer es añadir la internacionalización y utilizarla en los componentes necesarios.

AnaRangel / anarangel.github.io