Internationalization

Overview

starlight-telescope automatically supports Starlight’s multi-language features, providing locale-aware search results without additional configuration.

Current Limitations

• UI strings are English-only: Modal text (e.g., “Search pages…”, “No results found”) is currently hardcoded in English. Custom translations require plugin modification.
• No content fallback: If a page isn’t translated, it won’t appear in that locale’s search results (no fallback to default locale).

How It Works

1. The plugin detects the current locale from the URL path
2. Fetches page data for that locale (e.g., /fr/pages.json)
3. Filters recent and pinned pages to the current locale
4. Results only include pages from the active locale

Locale Detection

The plugin uses path-based locale detection matching Starlight’s conventions:

URL	Detected Locale
/getting-started/	Default (root)
/fr/getting-started/	French
/es/getting-started/	Spanish
/zh-cn/getting-started/	Chinese (Simplified)

Supported Locale Formats

• Two-letter codes: en, fr, de, es, ja
• Region codes: en-us, pt-br, zh-cn, zh-tw

Fallback Behavior

If a user visits a URL with an unrecognized locale prefix, the plugin falls back to the default locale’s page data.

Configuration

No additional configuration is needed. The plugin automatically integrates with Starlight’s existing locale setup:

astro.config.mjs

starlight({
  defaultLocale: 'root',
  locales: {
    root: { label: 'English', lang: 'en' },
    fr: { label: 'Français', lang: 'fr' },
    es: { label: 'Español', lang: 'es' },
  },
  plugins: [starlightTelescope()],
})

Per-Locale Data Endpoints

Each locale has its own pages.json endpoint automatically generated:

Locale	Endpoint
Default (root)	/pages.json
French	/fr/pages.json
Spanish	/es/pages.json

These endpoints include only the pages for that specific locale.

Storage Isolation

Recent and pinned pages are validated per-locale:

• A page pinned in English won’t appear when viewing French docs
• Recently visited English pages won’t show in the Spanish locale
• This prevents confusion when switching between language versions

Locale-Aware Navigation

When you select a page from search results, the navigation respects the current locale:

• Searching from /fr/getting-started/ navigates to French pages
• Searching from /getting-started/ navigates to default locale pages

Page Data Structure

Each page in pages.json includes:

{
  "title": "Getting Started",
  "path": "/getting-started/",
  "description": "Install and configure the plugin"
}

For translated pages:

{
  "title": "Commencer",
  "path": "/fr/getting-started/",
  "description": "Installer et configurer le plugin"
}

Partial Translations

If your documentation is partially translated:

• Users in the French locale only see French pages in search
• Missing translations won’t appear (no fallback to default locale in search)
• This ensures users only navigate to pages in their selected language