@astrojs/starlight 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @astrojs/starlight
 
+## 0.28.0
+
+### Minor Changes
+
+- [#1923](https://github.com/withastro/starlight/pull/1923) [`5269aad`](https://github.com/withastro/starlight/commit/5269aad928773ae08b35ba8e19c0f2832d0d2c89) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Overhauls the built-in localization system which is now powered by the [`i18next`](https://www.i18next.com/) library and available to use anywhere in your documentation website.
+
+  See the [“Using UI translations”](https://starlight.astro.build/guides/i18n/#using-ui-translations) guide to learn more about how to access built-in UI labels or your own custom strings in your project. Plugin authors can also use the new [`injectTranslations()`](https://starlight.astro.build/reference/plugins/#injecttranslations) helper to add or update translation strings.
+
+  ⚠️ **BREAKING CHANGE:** The `Astro.props.labels` props has been removed from the props passed down to custom component overrides.
+
+  If you are relying on `Astro.props.labels` (for example to read a built-in UI label), you will need to update your code to use the new [`Astro.locals.t()`](https://starlight.astro.build/guides/i18n/#using-ui-translations) helper instead.
+
+  ```astro
+  ---
+  import type { Props } from '@astrojs/starlight/props';
+  // The `search.label` UI label for this page’s language:
+  const searchLabel = Astro.locals.t('search.label');
+  ---
+  ```
+
+- [#2285](https://github.com/withastro/starlight/pull/2285) [`7286220`](https://github.com/withastro/starlight/commit/728622037602999ed67dedc2757ca5654236feb8) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for translating sidebar badges.
+
+- [#1923](https://github.com/withastro/starlight/pull/1923) [`5269aad`](https://github.com/withastro/starlight/commit/5269aad928773ae08b35ba8e19c0f2832d0d2c89) Thanks [@HiDeoo](https://github.com/HiDeoo)! - ⚠️ **BREAKING CHANGE:** The minimum supported version of Astro is now 4.14.0
+
+  Please update Astro and Starlight together:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
+### Patch Changes
+
+- [#2327](https://github.com/withastro/starlight/pull/2327) [`d7a295e`](https://github.com/withastro/starlight/commit/d7a295e5f63171c7eee9fc11333157d8c7e6c803) Thanks [@tritao](https://github.com/tritao)! - Fixes restoration of remark directives for nodes with custom data attached.
+
+## 0.27.1
+
+### Patch Changes
+
+- [#2303](https://github.com/withastro/starlight/pull/2303) [`f92791a`](https://github.com/withastro/starlight/commit/f92791aa1d1ec3d5498e445a078f7143fef60553) Thanks [@delucis](https://github.com/delucis)! - Fixes resolution for the internal module Git virtual module in projects with special characters in the file path
+
 ## 0.27.0
 
 ### Minor Changes

package/components/DraftContentNotice.astro

@@ -1,8 +1,6 @@
 ---
 import ContentNotice from './ContentNotice.astro';
 import type { Props } from '../props';
-
-const { labels } = Astro.props;
 ---
 
-<ContentNotice icon="warning" label={labels['page.draft']} />
+<ContentNotice icon="warning" label={Astro.locals.t('page.draft')} />

package/components/EditLink.astro

@@ -2,14 +2,14 @@
 import Icon from '../user-components/Icon.astro';
 import type { Props } from '../props';
 
-const { editUrl, labels } = Astro.props;
+const { editUrl } = Astro.props;
 ---
 
 {
 	editUrl && (
 		<a href={editUrl} class="sl-flex">
 			<Icon name="pencil" size="1.2em" />
-			{labels['page.editLink']}
+			{Astro.locals.t('page.editLink')}
 		</a>
 	)
 }

package/components/FallbackContentNotice.astro

@@ -1,8 +1,6 @@
 ---
 import ContentNotice from './ContentNotice.astro';
 import type { Props } from '../props';
-
-const { labels } = Astro.props;
 ---
 
-<ContentNotice icon="warning" label={labels['i18n.untranslatedContent']} />
+<ContentNotice icon="warning" label={Astro.locals.t('i18n.untranslatedContent')} />

package/components/Footer.astro

@@ -18,7 +18,7 @@ import { Icon } from '../components';
 	{
 		config.credits && (
 			<a class="kudos sl-flex" href="https://starlight.astro.build">
-				<Icon name={'starlight'} /> {Astro.props.labels['builtWithStarlight.label']}
+				<Icon name={'starlight'} /> {Astro.locals.t('builtWithStarlight.label')}
 			</a>
 		)
 	}

package/components/LanguageSelect.astro

@@ -10,8 +10,6 @@ import type { Props } from '../props';
 function localizedPathname(locale: string | undefined): string {
 	return localizedUrl(Astro.url, locale).pathname;
 }
-
-const { labels } = Astro.props;
 ---
 
 {
@@ -19,7 +17,7 @@ const { labels } = Astro.props;
 		<starlight-lang-select>
 			<Select
 				icon="translate"
-				label={labels['languageSelect.accessibleLabel']}
+				label={Astro.locals.t('languageSelect.accessibleLabel')}
 				value={localizedPathname(Astro.props.locale)}
 				options={Object.entries(config.locales).map(([code, locale]) => ({
 					value: localizedPathname(code),

package/components/LastUpdated.astro

@@ -1,13 +1,13 @@
 ---
 import type { Props } from '../props';
 
-const { labels, lang, lastUpdated } = Astro.props;
+const { lang, lastUpdated } = Astro.props;
 ---
 
 {
 	lastUpdated && (
 		<p>
-			{labels['page.lastUpdated']}{' '}
+			{Astro.locals.t('page.lastUpdated')}{' '}
 			<time datetime={lastUpdated.toISOString()}>
 				{lastUpdated.toLocaleDateString(lang, { dateStyle: 'medium', timeZone: 'UTC' })}
 			</time>

package/components/MobileMenuToggle.astro

@@ -1,14 +1,12 @@
 ---
 import type { Props } from '../props';
 import Icon from '../user-components/Icon.astro';
-
-const { labels } = Astro.props;
 ---
 
 <starlight-menu-button>
 	<button
 		aria-expanded="false"
-		aria-label={labels['menuButton.accessibleLabel']}
+		aria-label={Astro.locals.t('menuButton.accessibleLabel')}
 		aria-controls="starlight__sidebar"
 		class="sl-flex md:sl-hidden"
 	>

package/components/MobileTableOfContents.astro

@@ -3,7 +3,7 @@ import Icon from '../user-components/Icon.astro';
 import TableOfContentsList from './TableOfContents/TableOfContentsList.astro';
 import type { Props } from '../props';
 
-const { labels, toc } = Astro.props;
+const { toc } = Astro.props;
 ---
 
 {
@@ -13,7 +13,7 @@ const { labels, toc } = Astro.props;
 				<details id="starlight__mobile-toc">
 					<summary id="starlight__on-this-page--mobile" class="sl-flex">
 						<div class="toggle sl-flex">
-							{labels['tableOfContents.onThisPage']}
+							{Astro.locals.t('tableOfContents.onThisPage')}
 							<Icon name={'right-caret'} class="caret" size="1rem" />
 						</div>
 						<span class="display-current" />

package/components/PageFrame.astro

@@ -2,14 +2,14 @@
 import MobileMenuToggle from 'virtual:starlight/components/MobileMenuToggle';
 import type { Props } from '../props';
 
-const { hasSidebar, labels } = Astro.props;
+const { hasSidebar } = Astro.props;
 ---
 
 <div class="page sl-flex">
 	<header class="header"><slot name="header" /></header>
 	{
 		hasSidebar && (
-			<nav class="sidebar" aria-label={labels['sidebarNav.accessibleLabel']}>
+			<nav class="sidebar" aria-label={Astro.locals.t('sidebarNav.accessibleLabel')}>
 				<MobileMenuToggle {...Astro.props} />
 				<div id="starlight__sidebar" class="sidebar-pane">
 					<div class="sidebar-content sl-flex">

package/components/Pagination.astro

@@ -2,7 +2,7 @@
 import Icon from '../user-components/Icon.astro';
 import type { Props } from '../props';
 
-const { dir, labels, pagination } = Astro.props;
+const { dir, pagination } = Astro.props;
 const { prev, next } = pagination;
 const isRtl = dir === 'rtl';
 ---
@@ -13,7 +13,7 @@ const isRtl = dir === 'rtl';
 			<a href={prev.href} rel="prev">
 				<Icon name={isRtl ? 'right-arrow' : 'left-arrow'} size="1.5rem" />
 				<span>
-					{labels['page.previousLink']}
+					{Astro.locals.t('page.previousLink')}
 					<br />
 					<span class="link-title">{prev.label}</span>
 				</span>
@@ -25,7 +25,7 @@ const isRtl = dir === 'rtl';
 			<a href={next.href} rel="next">
 				<Icon name={isRtl ? 'left-arrow' : 'right-arrow'} size="1.5rem" />
 				<span>
-					{labels['page.nextLink']}
+					{Astro.locals.t('page.nextLink')}
 					<br />
 					<span class="link-title">{next.label}</span>
 				</span>

package/components/Search.astro

@@ -4,12 +4,10 @@ import Icon from '../user-components/Icon.astro';
 import project from 'virtual:starlight/project-context';
 import type { Props } from '../props';
 
-const { labels } = Astro.props;
-
 const pagefindTranslations = {
-	placeholder: labels['search.label'],
+	placeholder: Astro.locals.t('search.label'),
 	...Object.fromEntries(
-		Object.entries(labels)
+		Object.entries(Astro.locals.t.all())
 			.filter(([key]) => key.startsWith('pagefind.'))
 			.map(([key, value]) => [key.replace('pagefind.', ''), value])
 	),
@@ -23,28 +21,28 @@ const pagefindTranslations = {
 	<button
 		data-open-modal
 		disabled
-		aria-label={labels['search.label']}
+		aria-label={Astro.locals.t('search.label')}
 		aria-keyshortcuts="Control+K"
 	>
 		<Icon name="magnifier" />
-		<span class="sl-hidden md:sl-block" aria-hidden="true">{labels['search.label']}</span>
+		<span class="sl-hidden md:sl-block" aria-hidden="true">{Astro.locals.t('search.label')}</span>
 		<kbd class="sl-hidden md:sl-flex" style="display: none;">
-			<kbd>{labels['search.ctrlKey']}</kbd><kbd>K</kbd>
+			<kbd>{Astro.locals.t('search.ctrlKey')}</kbd><kbd>K</kbd>
 		</kbd>
 	</button>
 
-	<dialog style="padding:0" aria-label={labels['search.label']}>
+	<dialog style="padding:0" aria-label={Astro.locals.t('search.label')}>
 		<div class="dialog-frame sl-flex">
 			{
 				/* TODO: Make the layout of this button flexible to accommodate different word lengths. Currently hard-coded for English: “Cancel” */
 			}
 			<button data-close-modal class="sl-flex md:sl-hidden">
-				{labels['search.cancelLabel']}
+				{Astro.locals.t('search.cancelLabel')}
 			</button>
 			{
 				import.meta.env.DEV ? (
 					<div style="margin: auto; text-align: center; white-space: pre-line;" dir="ltr">
-						<p>{labels['search.devWarning']}</p>
+						<p>{Astro.locals.t('search.devWarning')}</p>
 					</div>
 				) : (
 					<div class="search-container">

package/components/SidebarRestorePoint.astro

@@ -1,7 +1,7 @@
 ---
 /** Unique symbol for storing a running index in `locals`. */
 const currentGroupIndexSymbol = Symbol.for('starlight-sidebar-group-index');
-const locals = Astro.locals as Record<typeof currentGroupIndexSymbol, number>;
+const locals = Astro.locals as App.Locals & { [currentGroupIndexSymbol]: number };
 
 /** The current sidebar group’s index retrieved from `locals` if set, starting at `0`. */
 const index = locals[currentGroupIndexSymbol] || 0;

package/components/SkipLink.astro

@@ -1,11 +1,9 @@
 ---
 import { PAGE_TITLE_ID } from '../constants';
 import type { Props } from '../props';
-
-const { labels } = Astro.props;
 ---
 
-<a href={`#${PAGE_TITLE_ID}`}>{labels['skipLink.label']}</a>
+<a href={`#${PAGE_TITLE_ID}`}>{Astro.locals.t('skipLink.label')}</a>
 
 <style>
 	a {

package/components/TableOfContents.astro

@@ -2,14 +2,14 @@
 import TableOfContentsList from './TableOfContents/TableOfContentsList.astro';
 import type { Props } from '../props';
 
-const { labels, toc } = Astro.props;
+const { toc } = Astro.props;
 ---
 
 {
 	toc && (
 		<starlight-toc data-min-h={toc.minHeadingLevel} data-max-h={toc.maxHeadingLevel}>
 			<nav aria-labelledby="starlight__on-this-page">
-				<h2 id="starlight__on-this-page">{labels['tableOfContents.onThisPage']}</h2>
+				<h2 id="starlight__on-this-page">{Astro.locals.t('tableOfContents.onThisPage')}</h2>
 				<TableOfContentsList toc={toc.items} />
 			</nav>
 		</starlight-toc>

package/components/ThemeSelect.astro

@@ -1,20 +1,18 @@
 ---
 import Select from './Select.astro';
 import type { Props } from '../props';
-
-const { labels } = Astro.props;
 ---
 
 <starlight-theme-select>
 	{/* TODO: Can we give this select a width that works well for each language’s strings? */}
 	<Select
 		icon="laptop"
-		label={labels['themeSelect.accessibleLabel']}
+		label={Astro.locals.t('themeSelect.accessibleLabel')}
 		value="auto"
 		options={[
-			{ label: labels['themeSelect.dark'], selected: false, value: 'dark' },
-			{ label: labels['themeSelect.light'], selected: false, value: 'light' },
-			{ label: labels['themeSelect.auto'], selected: true, value: 'auto' },
+			{ label: Astro.locals.t('themeSelect.dark'), selected: false, value: 'dark' },
+			{ label: Astro.locals.t('themeSelect.light'), selected: false, value: 'light' },
+			{ label: Astro.locals.t('themeSelect.auto'), selected: true, value: 'auto' },
 		]}
 		width="6.25em"
 	/>

package/i18n.d.ts

@@ -0,0 +1,18 @@
+/*
+ * This file imports the original `i18next` types and extends them to configure the
+ * Starlight namespace.
+ *
+ * Note that the top-level `import` makes this module non-ambient, so can’t be
+ * combined with other `.d.ts` files such as `locals.d.ts`.
+ */
+
+import 'i18next';
+
+declare module 'i18next' {
+	interface CustomTypeOptions {
+		defaultNS: typeof import('./utils/createTranslationSystem').I18nextNamespace;
+		resources: {
+			starlight: Record<import('./utils/createTranslationSystem').I18nKeys, string>;
+		};
+	}
+}

package/index.ts

@@ -1,3 +1,11 @@
+/**
+ * These triple-slash directives defines dependencies to various declaration files that will be
+ * loaded when a user imports the Starlight integration in their Astro configuration file. These
+ * directives must be first at the top of the file and can only be preceded by this comment.
+ */
+/// <reference path="./locals.d.ts" />
+/// <reference path="./i18n.d.ts" />
+
 import mdx from '@astrojs/mdx';
 import type { AstroIntegration } from 'astro';
 import { spawn } from 'node:child_process';
@@ -9,7 +17,12 @@ import { starlightSitemap } from './integrations/sitemap';
 import { vitePluginStarlightUserConfig } from './integrations/virtual-user-config';
 import { rehypeRtlCodeSupport } from './integrations/code-rtl-support';
 import { createTranslationSystemFromFs } from './utils/translations-fs';
-import { runPlugins, type StarlightUserConfigWithPlugins } from './utils/plugins';
+import {
+	injectPluginTranslationsTypes,
+	runPlugins,
+	type PluginTranslations,
+	type StarlightUserConfigWithPlugins,
+} from './utils/plugins';
 import { processI18nConfig } from './utils/i18n';
 import type { StarlightConfig } from './types';
 
@@ -18,10 +31,12 @@ export default function StarlightIntegration({
 	...opts
 }: StarlightUserConfigWithPlugins): AstroIntegration {
 	let userConfig: StarlightConfig;
+	let pluginTranslations: PluginTranslations = {};
 	return {
 		name: '@astrojs/starlight',
 		hooks: {
 			'astro:config:setup': async ({
+				addMiddleware,
 				command,
 				config,
 				injectRoute,
@@ -42,10 +57,17 @@ export default function StarlightIntegration({
 					config.i18n
 				);
 
-				const { integrations } = pluginResult;
+				const integrations = pluginResult.integrations;
+				pluginTranslations = pluginResult.pluginTranslations;
 				userConfig = starlightConfig;
 
-				const useTranslations = createTranslationSystemFromFs(starlightConfig, config);
+				const useTranslations = createTranslationSystemFromFs(
+					starlightConfig,
+					config,
+					pluginTranslations
+				);
+
+				addMiddleware({ entrypoint: '@astrojs/starlight/locals', order: 'pre' });
 
 				if (!starlightConfig.disable404Route) {
 					injectRoute({
@@ -91,7 +113,9 @@ export default function StarlightIntegration({
 
 				updateConfig({
 					vite: {
-						plugins: [vitePluginStarlightUserConfig(command, starlightConfig, config)],
+						plugins: [
+							vitePluginStarlightUserConfig(command, starlightConfig, config, pluginTranslations),
+						],
 					},
 					markdown: {
 						remarkPlugins: [
@@ -112,6 +136,10 @@ export default function StarlightIntegration({
 				});
 			},
 
+			'astro:config:done': ({ injectTypes }) => {
+				injectPluginTranslationsTypes(pluginTranslations, injectTypes);
+			},
+
 			'astro:build:done': ({ dir }) => {
 				if (!userConfig.pagefind) return;
 				const targetDir = fileURLToPath(dir);

package/integrations/asides.ts

@@ -166,7 +166,7 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 			// children with the `directiveLabel` property set to true. We want to pass it as the title
 			// prop to <Aside>, so when we find a directive label, we store it for the title prop and
 			// remove the paragraph from the container’s children.
-			let title = t(`aside.${variant}`);
+			let title: string = t(`aside.${variant}`);
 			let titleNode: PhrasingContent[] = [{ type: 'text', value: title }];
 			const firstChild = node.children[0];
 			if (
@@ -227,7 +227,8 @@ export function remarkDirectivesRestoration() {
 			if (
 				index !== undefined &&
 				parent &&
-				(node.type === 'textDirective' || node.type === 'leafDirective')
+				(node.type === 'textDirective' || node.type === 'leafDirective') &&
+				node.data === undefined
 			) {
 				transformUnhandledDirective(node, index, parent);
 				return;

package/integrations/virtual-user-config.ts

@@ -3,6 +3,7 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { StarlightConfig } from '../utils/user-config';
 import { getAllNewestCommitDate } from '../utils/git';
+import type { PluginTranslations } from '../utils/plugins';
 
 function resolveVirtualModuleId<T extends string>(id: T): `\0${T}` {
 	return `\0${id}`;
@@ -19,7 +20,8 @@ export function vitePluginStarlightUserConfig(
 		trailingSlash,
 	}: Pick<AstroConfig, 'root' | 'srcDir' | 'trailingSlash'> & {
 		build: Pick<AstroConfig['build'], 'format'>;
-	}
+	},
+	pluginTranslations: PluginTranslations
 ): NonNullable<ViteUserConfig['plugins']>[number] {
 	/**
 	 * Resolves module IDs to a usable format:
@@ -31,6 +33,15 @@ export function vitePluginStarlightUserConfig(
 	const resolveId = (id: string, base = root) =>
 		JSON.stringify(id.startsWith('.') ? resolve(fileURLToPath(base), id) : id);
 
+	/**
+	 * Resolves a path to a Starlight file relative to this file.
+	 * @example
+	 * resolveLocalPath('../utils/git.ts');
+	 * // => '"/users/houston/docs/node_modules/@astrojs/starlight/utils/git.ts"'
+	 */
+	const resolveLocalPath = (path: string) =>
+		JSON.stringify(fileURLToPath(new URL(path, import.meta.url)));
+
 	const docsPath = resolve(fileURLToPath(srcDir), 'content/docs');
 
 	const virtualComponentModules = Object.fromEntries(
@@ -51,9 +62,9 @@ export function vitePluginStarlightUserConfig(
 		})}`,
 		'virtual:starlight/git-info':
 			(command !== 'build'
-				? `import { makeAPI } from '${new URL('../utils/git.ts', import.meta.url)}';` +
+				? `import { makeAPI } from ${resolveLocalPath('../utils/git.ts')};` +
 					`const api = makeAPI(${JSON.stringify(docsPath)});`
-				: `import { makeAPI } from '${new URL('../utils/gitInlined.ts', import.meta.url)}';` +
+				: `import { makeAPI } from ${resolveLocalPath('../utils/gitInlined.ts')};` +
 					`const api = makeAPI(${JSON.stringify(getAllNewestCommitDate(docsPath))});`) +
 			'export const getNewestCommitDate = api.getNewestCommitDate;',
 		'virtual:starlight/user-css': opts.customCss.map((id) => `import ${resolveId(id)};`).join(''),
@@ -71,6 +82,7 @@ export function vitePluginStarlightUserConfig(
 				userCollections = (await import(${resolveId('./content/config.ts', srcDir)})).collections;
 			} catch {}
 			export const collections = userCollections;`,
+		'virtual:starlight/plugin-translations': `export default ${JSON.stringify(pluginTranslations)}`,
 		...virtualComponentModules,
 	} satisfies Record<string, string>;
 

package/locals.d.ts

@@ -0,0 +1,17 @@
+/**
+ * This namespace is reserved for Starlight (only used for i18n at the moment).
+ * It can be extended by plugins using module augmentation and interface merging.
+ * For an example, see: https://starlight.astro.build/reference/plugins/#injecttranslations
+ */
+declare namespace StarlightApp {
+	interface I18n {}
+}
+
+/**
+ * Extending Astro’s `App.Locals` interface registers types for the middleware added by Starlight.
+ */
+declare namespace App {
+	interface Locals {
+		t: import('./utils/createTranslationSystem').I18nT;
+	}
+}

package/locals.ts

@@ -0,0 +1,8 @@
+import { defineMiddleware } from 'astro:middleware';
+import { useTranslations } from './utils/translations';
+
+export const onRequest = defineMiddleware((context, next) => {
+	context.locals.t = useTranslations(context.currentLocale);
+
+	return next();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -21,6 +21,7 @@
   "type": "module",
   "exports": {
     ".": "./index.ts",
+    "./locals": "./locals.ts",
     "./components": "./components.ts",
     "./components/LanguageSelect.astro": {
       "types": "./components/LanguageSelect.astro.tsx",
@@ -166,7 +167,7 @@
     "./style/markdown.css": "./style/markdown.css"
   },
   "peerDependencies": {
-    "astro": "^4.8.6"
+    "astro": "^4.14.0"
   },
   "devDependencies": {
     "@astrojs/markdown-remark": "^5.1.0",
@@ -189,6 +190,7 @@
     "hast-util-select": "^6.0.2",
     "hast-util-to-string": "^3.0.0",
     "hastscript": "^9.0.0",
+    "i18next": "^23.11.5",
     "mdast-util-directive": "^3.0.0",
     "mdast-util-to-markdown": "^2.1.0",
     "mdast-util-to-string": "^4.0.0",

package/schemas/badge.ts

@@ -1,13 +1,19 @@
 import { z } from 'astro/zod';
 
-const badgeSchema = () =>
-	z.object({
-		variant: z.enum(['note', 'danger', 'success', 'caution', 'tip', 'default']).default('default'),
-		text: z.string(),
-		class: z.string().optional(),
-	});
-
-export const BadgeComponentSchema = badgeSchema()
+const badgeBaseSchema = z.object({
+	variant: z.enum(['note', 'danger', 'success', 'caution', 'tip', 'default']).default('default'),
+	class: z.string().optional(),
+});
+
+const badgeSchema = badgeBaseSchema.extend({
+	text: z.string(),
+});
+
+const i18nBadgeSchema = badgeBaseSchema.extend({
+	text: z.union([z.string(), z.record(z.string())]),
+});
+
+export const BadgeComponentSchema = badgeSchema
 	.extend({
 		size: z.enum(['small', 'medium', 'large']).default('small'),
 	})
@@ -17,7 +23,7 @@ export type BadgeComponentProps = z.input<typeof BadgeComponentSchema>;
 
 export const BadgeConfigSchema = () =>
 	z
-		.union([z.string(), badgeSchema()])
+		.union([z.string(), badgeSchema])
 		.transform((badge) => {
 			if (typeof badge === 'string') {
 				return { variant: 'default' as const, text: badge };
@@ -26,4 +32,8 @@ export const BadgeConfigSchema = () =>
 		})
 		.optional();
 
-export type Badge = z.output<ReturnType<typeof badgeSchema>>;
+export const I18nBadgeConfigSchema = () => z.union([z.string(), i18nBadgeSchema]).optional();
+
+export type Badge = z.output<typeof badgeSchema>;
+export type I18nBadge = z.output<typeof i18nBadgeSchema>;
+export type I18nBadgeConfig = z.output<ReturnType<typeof I18nBadgeConfigSchema>>;

package/schemas/sidebar.ts

@@ -1,7 +1,7 @@
 import type { AstroBuiltinAttributes } from 'astro';
 import type { HTMLAttributes } from 'astro/types';
 import { z } from 'astro/zod';
-import { BadgeConfigSchema } from './badge';
+import { I18nBadgeConfigSchema } from './badge';
 import { stripLeadingAndTrailingSlashes } from '../utils/path';
 
 const SidebarBaseSchema = z.object({
@@ -9,8 +9,8 @@ const SidebarBaseSchema = z.object({
 	label: z.string(),
 	/** Translations of the `label` for each supported language. */
 	translations: z.record(z.string()).default({}),
-	/** Adds a badge to the link item */
-	badge: BadgeConfigSchema(),
+	/** Adds a badge to the item */
+	badge: I18nBadgeConfigSchema(),
 });
 
 const SidebarGroupSchema = SidebarBaseSchema.extend({

package/utils/createTranslationSystem.ts

@@ -1,27 +1,60 @@
+import i18next, { type ExistsFunction, type TFunction } from 'i18next';
 import type { i18nSchemaOutput } from '../schemas/i18n';
 import builtinTranslations from '../translations/index';
 import { BuiltInDefaultLocale } from './i18n';
 import type { StarlightConfig } from './user-config';
+import type { UserI18nKeys, UserI18nSchema } from './translations';
+
+/**
+ * The namespace for i18next resources used by Starlight.
+ * All translations handled by Starlight are stored in the same namespace and Starlight always use
+ * a new instance of i18next configured for this namespace.
+ */
+export const I18nextNamespace = 'starlight' as const;
 
 export function createTranslationSystem<T extends i18nSchemaOutput>(
+	config: Pick<StarlightConfig, 'defaultLocale' | 'locales'>,
 	userTranslations: Record<string, T>,
-	config: Pick<StarlightConfig, 'defaultLocale' | 'locales'>
+	pluginTranslations: Record<string, T> = {}
 ) {
-	/** User-configured default locale. */
-	const defaultLocale = config.defaultLocale?.locale || 'root';
+	const defaultLocale =
+		config.defaultLocale.lang || config.defaultLocale?.locale || BuiltInDefaultLocale.lang;
 
-	/** Default map of UI strings based on Starlight and user-configured defaults. */
-	const defaults = buildDictionary(
-		builtinTranslations.en!,
-		userTranslations.en,
-		builtinTranslations[defaultLocale] || builtinTranslations[stripLangRegion(defaultLocale)],
-		userTranslations[defaultLocale]
-	);
+	const translations = {
+		[defaultLocale]: buildResources(
+			builtinTranslations[defaultLocale],
+			builtinTranslations[stripLangRegion(defaultLocale)],
+			pluginTranslations[defaultLocale],
+			userTranslations[defaultLocale]
+		),
+	};
+
+	if (config.locales) {
+		for (const locale in config.locales) {
+			const lang = localeToLang(locale, config.locales, config.defaultLocale);
+
+			translations[lang] = buildResources(
+				builtinTranslations[lang] || builtinTranslations[stripLangRegion(lang)],
+				pluginTranslations[lang],
+				userTranslations[lang]
+			);
+		}
+	}
+
+	const i18n = i18next.createInstance();
+	i18n.init({
+		resources: translations,
+		fallbackLng:
+			config.defaultLocale.lang || config.defaultLocale?.locale || BuiltInDefaultLocale.lang,
+	});
 
 	/**
 	 * Generate a utility function that returns UI strings for the given `locale`.
 	 *
-	 * Also includes an `all()` method for getting the entire dictionary.
+	 * Also includes a few utility methods:
+	 * - `all()` method for getting the entire dictionary.
+	 * - `exists()` method for checking if a key exists in the dictionary.
+	 * - `dir()` method for getting the text direction of the locale.
 	 *
 	 * @param {string | undefined} [locale]
 	 * @example
@@ -30,16 +63,19 @@ export function createTranslationSystem<T extends i18nSchemaOutput>(
 	 * // => 'Search'
 	 * const dictionary = t.all();
 	 * // => { 'skipLink.label': 'Skip to content', 'search.label': 'Search', ... }
+	 * const exists = t.exists('search.label');
+	 * // => true
+	 * const dir = t.dir();
+	 * // => 'ltr'
 	 */
-	return function useTranslations(locale: string | undefined) {
+	return (locale: string | undefined) => {
 		const lang = localeToLang(locale, config.locales, config.defaultLocale);
-		const dictionary = buildDictionary(
-			defaults,
-			builtinTranslations[lang] || builtinTranslations[stripLangRegion(lang)],
-			userTranslations[lang]
-		);
-		const t = <K extends keyof typeof dictionary>(key: K) => dictionary[key];
-		t.all = () => dictionary;
+
+		const t = i18n.getFixedT(lang, I18nextNamespace) as I18nT;
+		t.all = () => i18n.getResourceBundle(lang, I18nextNamespace);
+		t.exists = (key, options) => i18n.exists(key, { lng: lang, ns: I18nextNamespace, ...options });
+		t.dir = (dirLang = lang) => i18n.dir(dirLang);
+
 		return t;
 	};
 }
@@ -70,12 +106,11 @@ function localeToLang(
 
 type BuiltInStrings = (typeof builtinTranslations)['en'];
 
-/** Build a dictionary by layering preferred translation sources. */
-function buildDictionary<T extends Record<string, string | undefined>>(
-	base: BuiltInStrings,
+/** Build an i18next resources dictionary by layering preferred translation sources. */
+function buildResources<T extends Record<string, string | undefined>>(
 	...dictionaries: (T | BuiltInStrings | undefined)[]
-): BuiltInStrings & T {
-	const dictionary = { ...base };
+): { [I18nextNamespace]: BuiltInStrings & T } {
+	const dictionary: Partial<BuiltInStrings> = {};
 	// Iterate over alternate dictionaries to avoid overwriting preceding values with `undefined`.
 	for (const dict of dictionaries) {
 		for (const key in dict) {
@@ -83,5 +118,13 @@ function buildDictionary<T extends Record<string, string | undefined>>(
 			if (value) dictionary[key as keyof typeof dictionary] = value;
 		}
 	}
-	return dictionary as BuiltInStrings & T;
+	return { [I18nextNamespace]: dictionary as BuiltInStrings & T };
 }
+
+export type I18nKeys = UserI18nKeys | keyof StarlightApp.I18n;
+
+export type I18nT = TFunction<'starlight', undefined> & {
+	all: () => UserI18nSchema;
+	exists: ExistsFunction;
+	dir: (lang?: string) => 'ltr' | 'rtl';
+};

package/utils/i18n.ts

@@ -2,6 +2,26 @@ import type { AstroConfig } from 'astro';
 import { AstroError } from 'astro/errors';
 import type { StarlightConfig } from './user-config';
 
+/**
+ * A proxy object that throws an error when a user tries to access the deprecated `labels` prop in
+ * a component override.
+ *
+ * @todo Remove in a future release once people have updated — no later than v1.
+ */
+export const DeprecatedLabelsPropProxy = new Proxy<Record<string, never>>(
+	{},
+	{
+		get(_, key) {
+			const label = String(key);
+			throw new AstroError(
+				`The \`labels\` prop in component overrides has been removed.`,
+				`Replace \`Astro.props.labels["${label}"]\` with \`Astro.locals.t("${label}")\` instead.\n` +
+					'For more information see https://starlight.astro.build/guides/i18n/#using-ui-translations'
+			);
+		},
+	}
+);
+
 /**
  * A list of well-known right-to-left languages used as a fallback when determining the text
  * direction of a locale is not supported by the `Intl.Locale` API in the current environment.

package/utils/navigation.ts

@@ -1,6 +1,6 @@
 import { AstroError } from 'astro/errors';
 import config from 'virtual:starlight/user-config';
-import type { Badge } from '../schemas/badge';
+import type { Badge, I18nBadge, I18nBadgeConfig } from '../schemas/badge';
 import type { PrevNextLinkConfig } from '../schemas/prevNextLink';
 import type {
 	AutoSidebarGroup,
@@ -11,7 +11,7 @@ import type {
 } from '../schemas/sidebar';
 import { createPathFormatter } from './createPathFormatter';
 import { formatPath } from './format-path';
-import { pickLang } from './i18n';
+import { BuiltInDefaultLocale, pickLang } from './i18n';
 import { ensureLeadingSlash, ensureTrailingSlash, stripLeadingAndTrailingSlashes } from './path';
 import { getLocaleRoutes, routes, type Route } from './routing';
 import { localeToLang, slugToPathname } from './slugs';
@@ -79,12 +79,13 @@ function configItemToEntry(
 	} else if ('slug' in item) {
 		return linkFromInternalSidebarLinkItem(item, locale, currentPathname);
 	} else {
+		const label = pickLang(item.translations, localeToLang(locale)) || item.label;
 		return {
 			type: 'group',
-			label: pickLang(item.translations, localeToLang(locale)) || item.label,
+			label,
 			entries: item.items.map((i) => configItemToEntry(i, currentPathname, locale, routes)),
 			collapsed: item.collapsed,
-			badge: item.badge,
+			badge: getSidebarBadge(item.badge, locale, label),
 		};
 	}
 }
@@ -106,12 +107,13 @@ function groupFromAutogenerateConfig(
 			doc.id.startsWith(localeDir + '/')
 	);
 	const tree = treeify(dirDocs, localeDir);
+	const label = pickLang(item.translations, localeToLang(locale)) || item.label;
 	return {
 		type: 'group',
-		label: pickLang(item.translations, localeToLang(locale)) || item.label,
+		label,
 		entries: sidebarFromDir(tree, currentPathname, locale, subgroupCollapsed ?? item.collapsed),
 		collapsed: item.collapsed,
-		badge: item.badge,
+		badge: getSidebarBadge(item.badge, locale, label),
 	};
 }
 
@@ -131,7 +133,13 @@ function linkFromSidebarLinkItem(
 		if (locale) href = '/' + locale + href;
 	}
 	const label = pickLang(item.translations, localeToLang(locale)) || item.label;
-	return makeSidebarLink(href, label, currentPathname, item.badge, item.attrs);
+	return makeSidebarLink(
+		href,
+		label,
+		currentPathname,
+		getSidebarBadge(item.badge, locale, label),
+		item.attrs
+	);
 }
 
 /** Create a link entry from an automatic internal link item in user config. */
@@ -161,7 +169,13 @@ function linkFromInternalSidebarLinkItem(
 	}
 	const label =
 		pickLang(item.translations, localeToLang(locale)) || item.label || entry.entry.data.title;
-	return makeSidebarLink(entry.slug, label, currentPathname, item.badge, item.attrs);
+	return makeSidebarLink(
+		entry.slug,
+		label,
+		currentPathname,
+		getSidebarBadge(item.badge, locale, label),
+		item.attrs
+	);
 }
 
 /** Process sidebar link options to create a link entry. */
@@ -446,3 +460,38 @@ function stripExtension(path: string) {
 	const periodIndex = path.lastIndexOf('.');
 	return path.slice(0, periodIndex > -1 ? periodIndex : undefined);
 }
+
+/** Get a sidebar badge for a given item. */
+function getSidebarBadge(
+	config: I18nBadgeConfig,
+	locale: string | undefined,
+	itemLabel: string
+): Badge | undefined {
+	if (!config) return;
+	if (typeof config === 'string') {
+		return { variant: 'default', text: config };
+	}
+	return { ...config, text: getSidebarBadgeText(config.text, locale, itemLabel) };
+}
+
+/** Get the badge text for a sidebar item. */
+function getSidebarBadgeText(
+	text: I18nBadge['text'],
+	locale: string | undefined,
+	itemLabel: string
+): string {
+	if (typeof text === 'string') return text;
+	const defaultLang =
+		config.defaultLocale?.lang || config.defaultLocale?.locale || BuiltInDefaultLocale.lang;
+	const defaultText = text[defaultLang];
+
+	if (!defaultText) {
+		throw new AstroError(
+			`The badge text for "${itemLabel}" must have a key for the default language "${defaultLang}".`,
+			'Update the Starlight config to include a badge text for the default language.\n' +
+				'Learn more about sidebar badges internationalization at https://starlight.astro.build/guides/sidebar/#internationalization-with-badges'
+		);
+	}
+
+	return pickLang(text, localeToLang(locale)) || defaultText;
+}

package/utils/plugins.ts

@@ -1,8 +1,9 @@
-import type { AstroIntegration } from 'astro';
+import type { AstroIntegration, HookParameters } from 'astro';
 import { z } from 'astro/zod';
 import { StarlightConfigSchema, type StarlightUserConfig } from '../utils/user-config';
 import { parseWithFriendlyErrors } from '../utils/error-map';
 import { AstroError } from 'astro/errors';
+import type { UserI18nSchema } from './translations';
 
 /**
  * Runs Starlight plugins in the order that they are configured after validating the user-provided
@@ -32,6 +33,8 @@ export async function runPlugins(
 
 	// A list of Astro integrations added by the various plugins.
 	const integrations: AstroIntegration[] = [];
+	// A list of translations injected by the various plugins keyed by locale.
+	const pluginTranslations: PluginTranslations = {};
 
 	for (const {
 		name,
@@ -70,6 +73,13 @@ export async function runPlugins(
 			command: context.command,
 			isRestart: context.isRestart,
 			logger: context.logger.fork(name),
+			injectTranslations(translations) {
+				// Merge the translations injected by the plugin.
+				for (const [locale, localeTranslations] of Object.entries(translations)) {
+					pluginTranslations[locale] ??= {};
+					Object.assign(pluginTranslations[locale]!, localeTranslations);
+				}
+			},
 		});
 	}
 
@@ -81,7 +91,34 @@ export async function runPlugins(
 		);
 	}
 
-	return { integrations, starlightConfig };
+	return { integrations, starlightConfig, pluginTranslations };
+}
+
+export function injectPluginTranslationsTypes(
+	translations: PluginTranslations,
+	injectTypes: HookParameters<'astro:config:done'>['injectTypes']
+) {
+	const allKeys = new Set<string>();
+
+	for (const localeTranslations of Object.values(translations)) {
+		for (const key of Object.keys(localeTranslations)) {
+			allKeys.add(key);
+		}
+	}
+
+	// If there are no translations to inject, we don't need to generate any types or cleanup
+	// previous ones as they will not be referenced anymore.
+	if (allKeys.size === 0) return;
+
+	injectTypes({
+		filename: 'i18n-plugins.d.ts',
+		content: `declare namespace StarlightApp {
+	type PluginUIStringKeys = {
+		${[...allKeys].map((key) => `'${key}': string;`).join('\n\t\t')}
+	};
+	interface I18n extends PluginUIStringKeys {}
+}`,
+	});
 }
 
 // https://github.com/withastro/astro/blob/910eb00fe0b70ca80bd09520ae100e8c78b675b5/packages/astro/src/core/config/schema.ts#L113
@@ -192,6 +229,32 @@ const starlightPluginSchema = baseStarlightPluginSchema.extend({
 					 * @see https://docs.astro.build/en/reference/integrations-reference/#astrointegrationlogger
 					 */
 					logger: z.any() as z.Schema<StarlightPluginContext['logger']>,
+					/**
+					 * A callback function to add or update translations strings.
+					 *
+					 * @see https://starlight.astro.build/guides/i18n/#extend-translation-schema
+					 *
+					 * @example
+					 * {
+					 * 	name: 'My Starlight Plugin',
+					 * 	hooks: {
+					 * 		setup({ injectTranslations }) {
+					 * 			injectTranslations({
+					 * 				en: {
+					 * 					'myPlugin.doThing': 'Do the thing',
+					 * 				},
+					 * 				fr: {
+					 * 					'myPlugin.doThing': 'Faire le truc',
+					 * 				},
+					 * 			});
+					 * 		}
+					 * 	}
+					 * }
+					 */
+					injectTranslations: z.function(
+						z.tuple([z.record(z.string(), z.record(z.string(), z.string()))]),
+						z.void()
+					),
 				}),
 			]),
 			z.union([z.void(), z.promise(z.void())])
@@ -222,3 +285,5 @@ export type StarlightPluginContext = Pick<
 	Parameters<NonNullable<AstroIntegration['hooks']['astro:config:setup']>>[0],
 	'command' | 'config' | 'isRestart' | 'logger'
 >;
+
+export type PluginTranslations = Record<string, UserI18nSchema & Record<string, string>>;

package/utils/route-data.ts

@@ -7,8 +7,9 @@ import { getPrevNextLinks, getSidebar, type SidebarEntry } from './navigation';
 import { ensureTrailingSlash } from './path';
 import type { Route } from './routing';
 import { localizedId } from './slugs';
-import { useTranslations } from './translations';
 import { formatPath } from './format-path';
+import { useTranslations } from './translations';
+import { DeprecatedLabelsPropProxy } from './i18n';
 
 export interface PageProps extends Route {
 	headings: MarkdownHeading[];
@@ -33,8 +34,8 @@ export interface StarlightRouteData extends Route {
 	lastUpdated: Date | undefined;
 	/** URL object for the address where this page can be edited if enabled. */
 	editUrl: URL | undefined;
-	/** Record of UI strings localized for the current page. */
-	labels: ReturnType<ReturnType<typeof useTranslations>['all']>;
+	/** @deprecated Use `Astro.locals.t()` instead. */
+	labels: Record<string, never>;
 }
 
 export function generateRouteData({
@@ -57,7 +58,7 @@ export function generateRouteData({
 		toc: getToC(props),
 		lastUpdated: getLastUpdated(props),
 		editUrl: getEditUrl(props),
-		labels: useTranslations(locale).all(),
+		labels: DeprecatedLabelsPropProxy,
 	};
 }
 

package/utils/starlight-page.ts

@@ -13,8 +13,9 @@ import {
 import type { StarlightDocsEntry } from './routing';
 import { slugToLocaleData, urlToSlug } from './slugs';
 import { getPrevNextLinks, getSidebarFromConfig } from './navigation';
-import { useTranslations } from './translations';
 import { docsSchema } from '../schema';
+import type { Prettify, RemoveIndexSignature } from './types';
+import { DeprecatedLabelsPropProxy } from './i18n';
 import { SidebarItemSchema } from '../schemas/sidebar';
 import type { StarlightConfig, StarlightUserConfig } from './user-config';
 
@@ -151,7 +152,7 @@ export async function generateStarlightPageRouteData({
 		entryMeta,
 		hasSidebar: props.hasSidebar ?? entry.data.template !== 'splash',
 		headings,
-		labels: useTranslations(localeData.locale).all(),
+		labels: DeprecatedLabelsPropProxy,
 		lastUpdated,
 		pagination: getPrevNextLinks(sidebar, config.pagination, entry.data),
 		sidebar,
@@ -214,19 +215,3 @@ async function getUserDocsSchema(): Promise<
 	const userCollections = (await import('virtual:starlight/collection-config')).collections;
 	return userCollections?.docs.schema ?? docsSchema();
 }
-
-// https://stackoverflow.com/a/66252656/1945960
-type RemoveIndexSignature<T> = {
-	[K in keyof T as string extends K
-		? never
-		: number extends K
-			? never
-			: symbol extends K
-				? never
-				: K]: T[K];
-};
-
-// https://www.totaltypescript.com/concepts/the-prettify-helper
-type Prettify<T> = {
-	[K in keyof T]: T[K];
-} & {};

package/utils/translations-fs.ts

@@ -11,9 +11,10 @@ import type { AstroConfig } from 'astro';
  *
  * @see [`./translations.ts`](./translations.ts)
  */
-export function createTranslationSystemFromFs(
+export function createTranslationSystemFromFs<T extends i18nSchemaOutput>(
 	opts: Pick<StarlightConfig, 'defaultLocale' | 'locales'>,
-	{ srcDir }: Pick<AstroConfig, 'srcDir'>
+	{ srcDir }: Pick<AstroConfig, 'srcDir'>,
+	pluginTranslations: Record<string, T> = {}
 ) {
 	/** All translation data from the i18n collection, keyed by `id`, which matches locale. */
 	let userTranslations: Record<string, i18nSchemaOutput> = {};
@@ -40,5 +41,5 @@ export function createTranslationSystemFromFs(
 		}
 	}
 
-	return createTranslationSystem(userTranslations, opts);
+	return createTranslationSystem(opts, userTranslations, pluginTranslations);
 }

package/utils/translations.ts

@@ -1,13 +1,16 @@
 import { getCollection, type CollectionEntry, type DataCollectionKey } from 'astro:content';
 import config from 'virtual:starlight/user-config';
+import pluginTranslations from 'virtual:starlight/plugin-translations';
 import type { i18nSchemaOutput } from '../schemas/i18n';
 import { createTranslationSystem } from './createTranslationSystem';
+import type { RemoveIndexSignature } from './types';
 
-type UserI18nSchema = 'i18n' extends DataCollectionKey
+export type UserI18nSchema = 'i18n' extends DataCollectionKey
 	? CollectionEntry<'i18n'> extends { data: infer T }
-		? T
+		? i18nSchemaOutput & T
 		: i18nSchemaOutput
 	: i18nSchemaOutput;
+export type UserI18nKeys = keyof RemoveIndexSignature<UserI18nSchema>;
 
 /** Get all translation data from the i18n collection, keyed by `id`, which matches locale. */
 async function loadTranslations() {
@@ -34,4 +37,8 @@ async function loadTranslations() {
  * const t = useTranslations('en');
  * const label = t('search.label'); // => 'Search'
  */
-export const useTranslations = createTranslationSystem(await loadTranslations(), config);
+export const useTranslations = createTranslationSystem(
+	config,
+	await loadTranslations(),
+	pluginTranslations
+);

package/utils/types.ts

@@ -0,0 +1,15 @@
+// https://stackoverflow.com/a/66252656/1945960
+export type RemoveIndexSignature<T> = {
+	[K in keyof T as string extends K
+		? never
+		: number extends K
+			? never
+			: symbol extends K
+				? never
+				: K]: T[K];
+};
+
+// https://www.totaltypescript.com/concepts/the-prettify-helper
+export type Prettify<T> = {
+	[K in keyof T]: T[K];
+} & {};

package/virtual.d.ts

@@ -28,6 +28,11 @@ declare module 'virtual:starlight/user-images' {
 	};
 }
 
+declare module 'virtual:starlight/plugin-translations' {
+	const PluginTranslations: import('./utils/plugins').PluginTranslations;
+	export default PluginTranslations;
+}
+
 declare module 'virtual:starlight/collection-config' {
 	export const collections: import('astro:content').ContentConfig['collections'] | undefined;
 }