Replace astro-i18next and HeadHrefLangs Component Due to Compatibility Issues

[JoblersTune]

Bumping up the @astrojs/starlight dependency caused compatibility issues with the HeadHrefLangs component that is part of the astro-i18next module. Unfortunately, it seems this module is no longer being maintained. HeadHrefLangs is a component from astro-i18next that generated tags with hreflang attributes for SEO, specifying alternate language versions of a webpage.

astro-i18next also adds in other internationalization features like i18next configurations. There needs be investigation of the best way to keep all this functionality while keeping everything updated. This either means exploring other community libraries, or use Astro's Built-in i18n Support. This also has limitations which is why it needs more work to figure out the best path.

Error

TypeError
An error occurred.
Cannot read properties of undefined (reading 'map')
components/HeadHrefLangs.astro:10:19
Open in editor
---
import i18next from "i18next";
import { localizeUrl } from "../..";

const supportedLanguages = i18next.languages;
const currentUrl = Astro.url.href;
---

{
  supportedLanguages.map((supportedLanguage) => (
^
    <link
      rel="alternate"
      hreflang={supportedLanguage}
      href={localizeUrl(currentUrl, supportedLanguage)}
    />
  ))
}
Stack Trace
TypeError: Cannot read properties of undefined (reading 'map')
    at /home/sarah/sarah-webmo/webmonetization/node_modules/astro-i18next/src/components/HeadHrefLangs.astro:10:19
    at AstroComponentInstance.HeadHrefLangs [as factory] (/home/sarah/sarah-webmo/webmonetization/node_modules/astro/dist/runtime/server/astro-component.js:16:12)
    at AstroComponentInstance.init (/home/sarah/sarah-webmo/webmonetization/node_modules/astro/dist/runtime/server/render/astro/instance.js:32:29)
    at AstroComponentInstance.render (/home/sarah/sarah-webmo/webmonetization/node_modules/astro/dist/runtime/server/render/astro/instance.js:42:36)
    at Object.render (/home/sarah/sarah-webmo/webmonetization/node_modules/astro/dist/runtime/server/render/component.js:367:22)
    at Module.renderChild (/home/sarah/sarah-webmo/webmonetization/node_modules/astro/dist/runtime/server/render/any.js:31:17)

Current Workaround

The dependencies can be updated by removing the import { HeadHrefLangs } from "astro-i18next/components"; and <HeadHrefLangs /> lines from src/layouts/Base.astro. See chore: basic dependency bump #485

[JoblersTune]

Migrating to Astro's Built-in i18n Support would look something like this:

export default defineConfig({
  site: 'https://webmonetization.org',
  integrations: [
  ],
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    fallback: {
      es: 'en',
      fr: 'en',
    },
    routing: {
      redirectToDefaultLocale: true
    }
  },
  server: {
    port: 1100,
  },
})

Problems with Starlight links validator

Using this approach is incompatible with also configuring Starlight separately for internationalisation. Only one or the other is permitted in the config file.

This configuration still provides all the functionality that the Starlight specific config did, but, now the Starlight links validator no longer recognises the links inside translated files as valid (even though they should point to the language they are in and if the page doesn't yet exist that is handled with a graceful redirect to English and a message informing the viewer that this page has not yet been translated.

This would mean ignoring all the links in translated files, which is not ideal

plugins: [
        starlightLinksValidator({
          errorOnFallbackPages: false,
          exclude: ['/es/docs/**', '/fr/docs/**', '/prob-revshare'],
        }),
      ],

Or, it means finding a different way around still using the built in internationalisation and get link validation in the docs.

Doesn't solve HeadHrefLangs

The astro-i18next library generated tags with hreflang attributes for SEO, specifying alternate language versions of a webpage. Using Astro's Built-in i18n Support doesn't have an 'out of the box' way of handling this.

Advantage

All the configuration is consolidated and will remain compatible.