Inconsistent Locale

The inconsistent locale error indicates that a link points to a page in a different locale than the current page. For example, a link from /fr/getting-started/ to /guides/usage/ changes the user from French to the root locale.

This behavior is controlled by the errorOnInconsistentLocale option. By default, links that point to a different locale do not report an error. When this option is enabled, links that move users to a different locale report an inconsistent locale error. This can be useful on multilingual sites, where forgetting to update a link to the current language can be confusing for users.

Example

For example, given the following project structure:

Directorysrc/
- Directorycontent/
  - Directorydocs/
    Directoryguides/
    usage.mdx
    getting-started.md
    Directoryfr/
    Directoryguides/
    usage.mdx
    getting-started.md
astro.config.mjs

With the following configuration in astro.config.mjs:

import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightLinksValidator from 'starlight-links-validator'

export default defineConfig({
  integrations: [
    starlight({
      locales: {
        root: { label: 'English', lang: 'en' },
        fr: { label: 'Français', lang: 'fr' },
      },
      plugins: [starlightLinksValidator({ errorOnInconsistentLocale: true })],
      title: 'My Docs',
    }),
  ],
})

And the following content in src/content/docs/fr/getting-started.md:

---
title: Mise en route
---

## Prochaines étapes

- [Guide d'utilisation](/guides/usage/)
- [Mettre à jour](#mettre-à-jour)

## Mettre à jour

Du contenu.

Running a production build reports the following error:

  ╭─ fr/getting-started.md
  ·
7 | /guides/usage/
  ·             ╰── inconsistent locale

╭─                               ─╮
· Found 1 invalid link in 1 file. ·
╰─                               ─╯

How to fix

To fix inconsistent locale errors, update each link so it points to the equivalent page in the current locale.

For this example:

Update /guides/usage/ to /fr/guides/usage/ so the link stays in the French locale.