Starlight overrides the defaultNS type definition of i18next so it conflicts with other i18next type definitions.

[lhr0909]

What version of starlight are you using?

0.30.0

What version of astro are you using?

5.1.1

What package manager are you using?

pnpm

What operating system are you using?

Mac

What browser are you using?

Chrome

Describe the Bug

I was integrating i18next into my Astro site with Starlight and found that the TypeScript compiler will force the defaultNS field for any i18next instance to be 'starlight', which will make the t function type errors if the keys don't match.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-ytqftcmh?file=src%2Fpages%2Ftest.astro

Participation

• I am willing to submit a pull request for this issue.

[lhr0909]

Seems like stackblitz doesn't have type checking, but this is what I have on my IDE:

the T function's Namespace field is forced to be 'starlight'

[delucis]

Ah, thanks for the heads up. Not sure this was something we considered while working on this feature.

For what it’s worth, I think you should be able to use Starlight’s Astro.locals.t() throughout your site even on non-Starlight pages (assuming they use the same locale prefixes in the URLs), so it might be possible to avoid additional set-up of i18next.

Still, it would be good to avoid this if possible. Happy to review a PR if anyone knows how to solve this!

[HiDeoo]

Like you mentioned, StackBlitz does not have proper type-checking but even after downloading the project locally, I am not able to reproduce the issue.

From quickly looking at the code, it seems that the repro does not include a declaration file for i18next so I added one in src/i18next.d.ts:

// src/i18next.d.ts
import "i18next";
// Import the base translation file
import en from "../public/locales/en/translation.json";

declare module "i18next" {
  interface CustomTypeOptions {
    // Define the default namespace
    defaultNS: "translation";
    resources: {
      // And the associated translations
      translation: typeof en;
    };
  }
}

It imports translation for the default language and defines the associated type for the translation namespace.

After doing so, it seems that everything works as expected:

• When using Astro.locals.t:
  • I get autocompletion for Starlight UI strings.
  • Unknown key are correctly highlighted as errors.
  • Keys from your custom translation file are correctly highlighted as errors.
• When using your t function:
  • I get autocompletion for keys from public/locales/en/translation.json.
  • Unknown key are correctly highlighted as errors.
  • Keys from Starlight UI are correctly highlighted as errors.