@astrojs/starlight 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @astrojs/starlight
 
+## 0.12.0
+
+### Minor Changes
+
+- [#995](https://github.com/withastro/starlight/pull/995) [`5bf4457`](https://github.com/withastro/starlight/commit/5bf44577634935b9fa6d50b040abcd680035075f) Thanks [@kevinzunigacuellar](https://github.com/kevinzunigacuellar)! - Adds support for adding sidebar badges to group headings
+
+- [#988](https://github.com/withastro/starlight/pull/988) [`977fe13`](https://github.com/withastro/starlight/commit/977fe135a74661300589898abe98aec73cad9ed3) Thanks [@magicDGS](https://github.com/magicDGS)! - Include social icon links in mobile menu
+
+- [#280](https://github.com/withastro/starlight/pull/280) [`72cca2d`](https://github.com/withastro/starlight/commit/72cca2d07644f00595da6ebf7d603adb282f359d) Thanks [@cbontems](https://github.com/cbontems)! - Support light & dark variants of the hero image.
+
+  ⚠️ **Potentially breaking change:** The `hero.image` schema is now slightly stricter than previously.
+
+  The `hero.image.html` property can no longer be used alongside the `hero.image.alt` or `hero.image.file` properties.
+  Previously, `html` was ignored when used with `file` and `alt` was ignored when used with `html`.
+  Now, those combinations will throw errors.
+  If you encounter errors, remove the `image.hero` property that is not in use.
+
+### Patch Changes
+
+- [#1004](https://github.com/withastro/starlight/pull/1004) [`7f92213`](https://github.com/withastro/starlight/commit/7f92213a0b93de5a844816841a6bc9cdd371de0c) Thanks [@nunhes](https://github.com/nunhes)! - Add Galician language support
+
+- [#1003](https://github.com/withastro/starlight/pull/1003) [`f1fdb50`](https://github.com/withastro/starlight/commit/f1fdb50daebe79548c7789d3f7dd968b261d2da7) Thanks [@delucis](https://github.com/delucis)! - Internal: refactor translation string loading to make translations available to Starlight integration code
+
+## 0.11.2
+
+### Patch Changes
+
+- [#944](https://github.com/withastro/starlight/pull/944) [`7a6446e`](https://github.com/withastro/starlight/commit/7a6446ebc61ba9cc36d1dcfd13db15c1533751ab) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fix issue with sidebar autogenerated groups configured with a directory containing leading or trailing slash
+
+- [#985](https://github.com/withastro/starlight/pull/985) [`92b3b57`](https://github.com/withastro/starlight/commit/92b3b575404d0dc34f720c0ba29d8ed50be98f58) Thanks [@delucis](https://github.com/delucis)! - Fix edit URLs for pages displaying fallback content
+
+- [#986](https://github.com/withastro/starlight/pull/986) [`0470734`](https://github.com/withastro/starlight/commit/0470734e0dc323f9945e06bee4338c2f777ba0d6) Thanks [@dreyfus92](https://github.com/dreyfus92)! - Prevent overscrolling on mobile table of contents by setting 'overscroll-behavior: contain'.
+
+- [#924](https://github.com/withastro/starlight/pull/924) [`39d6302`](https://github.com/withastro/starlight/commit/39d6302db42ee1105d690bbd3a66053e6b21e15a) Thanks [@kevinzunigacuellar](https://github.com/kevinzunigacuellar)! - Remove extra margin from markdown lists that uses inline code
+
+- [#814](https://github.com/withastro/starlight/pull/814) [`1e517d9`](https://github.com/withastro/starlight/commit/1e517d92a4cf146d2dcae58f7c4299d6f25ea73e) Thanks [@julien-deramond](https://github.com/julien-deramond)! - Prevent text from overflowing pagination items
+
 ## 0.11.1
 
 ### Patch Changes

package/components/Hero.astro

@@ -14,20 +14,34 @@ const imageAttrs = {
 	height: 400,
 	alt: image?.alt || '',
 };
+
+let darkImage: ImageMetadata | undefined;
+let lightImage: ImageMetadata | undefined;
+let rawHtml: string | undefined;
+if (image) {
+	if ('file' in image) {
+		darkImage = image.file;
+	} else if ('dark' in image) {
+		darkImage = image.dark;
+		lightImage = image.light;
+	} else {
+		rawHtml = image.html;
+	}
+}
 ---
 
 <div class="hero">
 	{
-		image?.file ? (
-			image.file.format === 'svg' ? (
-				<img src={image.file.src} {...imageAttrs} />
-			) : (
-				<Image src={image.file} {...imageAttrs} />
-			)
-		) : (
-			image?.html && <div class="hero-html sl-flex" set:html={image.html} />
+		darkImage && (
+			<Image
+				src={darkImage}
+				{...imageAttrs}
+				class:list={{ 'light:sl-hidden': Boolean(lightImage) }}
+			/>
 		)
 	}
+	{lightImage && <Image src={lightImage} {...imageAttrs} class="dark:sl-hidden" />}
+	{rawHtml && <div class="hero-html sl-flex" set:html={rawHtml} />}
 	<div class="sl-flex stack">
 		<div class="sl-flex copy">
 			<h1 id={PAGE_TITLE_ID} data-page-title set:html={title} />

package/components/MarkdownContent.astro

@@ -7,8 +7,8 @@ import type { Props } from '../props';
 <style>
 	.content
 		:global(
-			:not(a, strong, em, del, span, input)
-				+ :not(a, strong, em, del, span, input, :where(.not-content *))
+			:not(a, strong, em, del, span, input, code)
+				+ :not(a, strong, em, del, span, input, code, :where(.not-content *))
 		) {
 		margin-top: 1.5rem;
 	}

package/components/MobileMenuFooter.astro

@@ -1,17 +1,31 @@
 ---
-import { LanguageSelect, ThemeSelect } from 'virtual:starlight/components';
+import { LanguageSelect, ThemeSelect, SocialIcons } from 'virtual:starlight/components';
 import type { Props } from '../props';
 ---
 
 <div class="mobile-preferences sl-flex">
+	<div class="sl-flex social-icons">
+		<SocialIcons {...Astro.props} />
+	</div>
 	<ThemeSelect {...Astro.props} />
 	<LanguageSelect {...Astro.props} />
 </div>
 
 <style>
+	.social-icons {
+		margin-inline-end: auto;
+		gap: 1rem;
+		align-items: center;
+		padding-block: 1rem;
+	}
+	.social-icons:empty {
+		display: none;
+	}
 	.mobile-preferences {
 		justify-content: space-between;
+		flex-wrap: wrap;
 		border-top: 1px solid var(--sl-color-gray-6);
+		column-gap: 1rem;
 		padding: 0.5rem 0;
 	}
 </style>

package/components/MobileTableOfContents.astro

@@ -105,6 +105,7 @@ const t = useTranslations(locale);
 		overflow-y: auto;
 		background-color: var(--sl-color-black);
 		box-shadow: var(--sl-shadow-md);
+		overscroll-behavior: contain;
 	}
 </style>
 

package/components/Pagination.astro

@@ -9,7 +9,7 @@ const isRtl = dir === 'rtl';
 const t = useTranslations(locale);
 ---
 
-<div class="pagination-links sl-flex" dir={dir}>
+<div class="pagination-links" dir={dir}>
 	{
 		prev && (
 			<a href={prev.href} rel="prev">
@@ -38,7 +38,8 @@ const t = useTranslations(locale);
 
 <style>
 	.pagination-links {
-		flex-wrap: wrap;
+		display: grid;
+		grid-template-columns: repeat(auto-fit, minmax(min(18rem, 100%), 1fr));
 		gap: 1rem;
 	}
 
@@ -56,6 +57,7 @@ const t = useTranslations(locale);
 		text-decoration: none;
 		color: var(--sl-color-gray-2);
 		box-shadow: var(--sl-shadow-md);
+		overflow-wrap: anywhere;
 	}
 	[rel='next'] {
 		justify-content: end;
@@ -71,4 +73,8 @@ const t = useTranslations(locale);
 		font-size: var(--sl-text-2xl);
 		line-height: var(--sl-line-height-headings);
 	}
+
+	svg {
+		flex-shrink: 0;
+	}
 </style>

package/components/SidebarSublist.astro

@@ -36,7 +36,15 @@ interface Props {
 						open={flattenSidebar(entry.entries).some((i) => i.isCurrent) || !entry.collapsed}
 					>
 						<summary>
-							<span class="large">{entry.label}</span>
+							<div class="group-label">
+								<span class="large">{entry.label}</span>
+								{entry.badge && (
+									<>
+										{' '}
+										<Badge text={entry.badge.text} variant={entry.badge.variant} />
+									</>
+								)}
+							</div>
 							<Icon name="right-caret" class="caret" size="1.25rem" />
 						</summary>
 						<Astro.self sublist={entry.entries} nested />
@@ -78,7 +86,8 @@ interface Props {
 		display: flex;
 		align-items: center;
 		justify-content: space-between;
-		padding-inline: var(--sl-sidebar-item-padding-inline);
+		padding: 0.2em var(--sl-sidebar-item-padding-inline);
+		line-height: 1.4;
 		cursor: pointer;
 		user-select: none;
 	}
@@ -120,7 +129,8 @@ interface Props {
 		background-color: var(--sl-color-text-accent);
 	}
 
-	a > *:not(:last-child) {
+	a > *:not(:last-child),
+	.group-label > *:not(:last-child) {
 		margin-inline-end: 0.25em;
 	}
 

package/components/SiteTitle.astro

@@ -12,7 +12,7 @@ const href = pathWithBase(Astro.props.locale || '/');
 		config.logo && logos.dark && (
 			<>
 				<img
-					class:list={{ 'dark-only': !('src' in config.logo) }}
+					class:list={{ 'light:sl-hidden': !('src' in config.logo) }}
 					alt={config.logo.alt}
 					src={logos.dark.src}
 					width={logos.dark.width}
@@ -21,7 +21,7 @@ const href = pathWithBase(Astro.props.locale || '/');
 				{/* Show light alternate if a user configure both light and dark logos. */}
 				{!('src' in config.logo) && (
 					<img
-						class="light-only"
+						class="dark:sl-hidden"
 						alt={config.logo.alt}
 						src={logos.light?.src}
 						width={logos.light?.width}
@@ -56,10 +56,4 @@ const href = pathWithBase(Astro.props.locale || '/');
 		object-fit: contain;
 		object-position: 0 50%;
 	}
-	:global([data-theme='light']) .dark-only {
-		display: none;
-	}
-	:global([data-theme='dark']) .light-only {
-		display: none;
-	}
 </style>

package/index.ts

@@ -9,6 +9,7 @@ import { vitePluginStarlightUserConfig } from './integrations/virtual-user-confi
 import { errorMap } from './utils/error-map';
 import { StarlightConfigSchema, type StarlightUserConfig } from './utils/user-config';
 import { rehypeRtlCodeSupport } from './integrations/code-rtl-support';
+import { createTranslationSystemFromFs } from './utils/translations-fs';
 
 export default function StarlightIntegration(opts: StarlightUserConfig): AstroIntegration {
 	const parsedConfig = StarlightConfigSchema.safeParse(opts, { errorMap });
@@ -26,6 +27,7 @@ export default function StarlightIntegration(opts: StarlightUserConfig): AstroIn
 		name: '@astrojs/starlight',
 		hooks: {
 			'astro:config:setup': ({ config, injectRoute, updateConfig }) => {
+				const useTranslations = createTranslationSystemFromFs(userConfig, config);
 				injectRoute({
 					pattern: '404',
 					entryPoint: '@astrojs/starlight/404.astro',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",

package/schema.ts

@@ -3,16 +3,13 @@ import type { SchemaContext } from 'astro:content';
 import { HeadConfigSchema } from './schemas/head';
 import { PrevNextLinkConfigSchema } from './schemas/prevNextLink';
 import { TableOfContentsSchema } from './schemas/tableOfContents';
-import { Icons } from './components/Icons';
 import { BadgeConfigSchema } from './schemas/badge';
+import { HeroSchema } from './schemas/hero';
 import { SidebarLinkItemHTMLAttributesSchema } from './schemas/sidebar';
 export { i18nSchema } from './schemas/i18n';
 
-type IconName = keyof typeof Icons;
-const iconNames = Object.keys(Icons) as [IconName, ...IconName[]];
-
 export function docsSchema() {
-	return ({ image }: SchemaContext) =>
+	return (context: SchemaContext) =>
 		z.object({
 			/** The title of the current page. Required. */
 			title: z.string(),
@@ -45,56 +42,7 @@ export function docsSchema() {
 			template: z.enum(['doc', 'splash']).default('doc'),
 
 			/** Display a hero section on this page. */
-			hero: z
-				.object({
-					/**
-					 * The large title text to show. If not provided, will default to the top-level `title`.
-					 * Can include HTML.
-					 */
-					title: z.string().optional(),
-					/**
-					 * A short bit of text about your project.
-					 * Will be displayed in a smaller size below the title.
-					 */
-					tagline: z.string().optional(),
-					/** The image to use in the hero. You can provide either a relative `file` path or raw `html`. */
-					image: z
-						.object({
-							/** Alt text for screenreaders and other assistive technologies describing your hero image. */
-							alt: z.string().default(''),
-							/** Relative path to an image file in your repo, e.g. `../../assets/hero.png`. */
-							file: image().optional(),
-							/** Raw HTML string instead of an image file. Useful for inline SVGs or more complex hero content. */
-							html: z.string().optional(),
-						})
-						.optional(),
-					/** An array of call-to-action links displayed at the bottom of the hero. */
-					actions: z
-						.object({
-							/** Text label displayed in the link. */
-							text: z.string(),
-							/** Value for the link’s `href` attribute, e.g. `/page` or `https://mysite.com`. */
-							link: z.string(),
-							/** Button style to use. One of `primary`, `secondary`, or `minimal` (the default). */
-							variant: z.enum(['primary', 'secondary', 'minimal']).default('minimal'),
-							/**
-							 * An optional icon to display alongside the link text.
-							 * Can be an inline `<svg>` or the name of one of Starlight’s built-in icons.
-							 */
-							icon: z
-								.union([z.enum(iconNames), z.string().startsWith('<svg')])
-								.transform((icon) => {
-									const parsedIcon = z.enum(iconNames).safeParse(icon);
-									return parsedIcon.success
-										? ({ type: 'icon', name: parsedIcon.data } as const)
-										: ({ type: 'raw', html: icon } as const);
-								})
-								.optional(),
-						})
-						.array()
-						.default([]),
-				})
-				.optional(),
+			hero: HeroSchema(context).optional(),
 
 			/**
 			 * The last update date of the current page.

package/schemas/hero.ts

@@ -0,0 +1,70 @@
+import { z } from 'astro/zod';
+import type { SchemaContext } from 'astro:content';
+import { Icons } from '../components/Icons';
+
+type IconName = keyof typeof Icons;
+const iconNames = Object.keys(Icons) as [IconName, ...IconName[]];
+
+export const HeroSchema = ({ image }: SchemaContext) =>
+	z.object({
+		/**
+		 * The large title text to show. If not provided, will default to the top-level `title`.
+		 * Can include HTML.
+		 */
+		title: z.string().optional(),
+		/**
+		 * A short bit of text about your project.
+		 * Will be displayed in a smaller size below the title.
+		 */
+		tagline: z.string().optional(),
+		/** The image to use in the hero. You can provide either a relative `file` path or raw `html`. */
+		image: z
+			.union([
+				z.object({
+					/** Alt text for screenreaders and other assistive technologies describing your hero image. */
+					alt: z.string().default(''),
+					/** Relative path to an image file in your repo, e.g. `../../assets/hero.png`. */
+					file: image(),
+				}),
+				z.object({
+					/** Alt text for screenreaders and other assistive technologies describing your hero image. */
+					alt: z.string().default(''),
+					/** Relative path to an image file in your repo to use in dark mode, e.g. `../../assets/hero-dark.png`. */
+					dark: image(),
+					/** Relative path to an image file in your repo to use in light mode, e.g. `../../assets/hero-light.png`. */
+					light: image(),
+				}),
+				z
+					.object({
+						/** Raw HTML string instead of an image file. Useful for inline SVGs or more complex hero content. */
+						html: z.string(),
+					})
+					.transform(({ html }) => ({ html, alt: '' })),
+			])
+			.optional(),
+		/** An array of call-to-action links displayed at the bottom of the hero. */
+		actions: z
+			.object({
+				/** Text label displayed in the link. */
+				text: z.string(),
+				/** Value for the link’s `href` attribute, e.g. `/page` or `https://mysite.com`. */
+				link: z.string(),
+				/** Button style to use. One of `primary`, `secondary`, or `minimal` (the default). */
+				variant: z.enum(['primary', 'secondary', 'minimal']).default('minimal'),
+				/**
+				 * An optional icon to display alongside the link text.
+				 * Can be an inline `<svg>` or the name of one of Starlight’s built-in icons.
+				 */
+				icon: z
+					.union([z.enum(iconNames), z.string().startsWith('<svg')])
+					.transform((icon) => {
+						const parsedIcon = z.enum(iconNames).safeParse(icon);
+						return parsedIcon.success
+							? ({ type: 'icon', name: parsedIcon.data } as const)
+							: ({ type: 'raw', html: icon } as const);
+					})
+					.optional(),
+			})
+			.array()
+			.default([]),
+	});

package/schemas/i18n.ts

@@ -3,6 +3,7 @@ import { z } from 'astro/zod';
 export function i18nSchema() {
 	return starlightI18nSchema().merge(pagefindI18nSchema());
 }
+export type i18nSchemaOutput = z.output<ReturnType<typeof i18nSchema>>;
 
 export function builtinI18nSchema() {
 	return starlightI18nSchema().required().strict().merge(pagefindI18nSchema());

package/schemas/sidebar.ts

@@ -2,12 +2,15 @@ import type { AstroBuiltinAttributes } from 'astro';
 import type { HTMLAttributes } from 'astro/types';
 import { z } from 'astro/zod';
 import { BadgeConfigSchema } from './badge';
+import { stripLeadingAndTrailingSlashes } from '../utils/path';
 
 const SidebarBaseSchema = z.object({
 	/** The visible label for this item in the sidebar. */
 	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(),
 });
 
 const SidebarGroupSchema = SidebarBaseSchema.extend({
@@ -28,8 +31,6 @@ export const SidebarLinkItemHTMLAttributesSchema = () => linkHTMLAttributesSchem
 const SidebarLinkItemSchema = SidebarBaseSchema.extend({
 	/** The link to this item’s content. Can be a relative link to local files or the full URL of an external page. */
 	link: z.string(),
-	/** Adds a badge to the link item */
-	badge: BadgeConfigSchema(),
 	/** HTML attributes to add to the link item. */
 	attrs: SidebarLinkItemHTMLAttributesSchema(),
 });
@@ -39,7 +40,7 @@ const AutoSidebarGroupSchema = SidebarGroupSchema.extend({
 	/** Enable autogenerating a sidebar category from a specific docs directory. */
 	autogenerate: z.object({
 		/** The directory to generate sidebar items for. */
-		directory: z.string(),
+		directory: z.string().transform(stripLeadingAndTrailingSlashes),
 		/**
 		 * Whether the autogenerated subgroups should be collapsed by default.
 		 * Defaults to the `AutoSidebarGroup` `collapsed` value.

package/schemas/social.ts

@@ -1,33 +1,35 @@
 import { z } from 'astro/zod';
 
+export const socialLinks = [
+	'twitter',
+	'mastodon',
+	'github',
+	'gitlab',
+	'bitbucket',
+	'discord',
+	'gitter',
+	'codeberg',
+	'codePen',
+	'youtube',
+	'threads',
+	'linkedin',
+	'twitch',
+	'microsoftTeams',
+	'instagram',
+	'stackOverflow',
+	'x.com',
+	'telegram',
+	'rss',
+	'facebook',
+	'email',
+	'reddit',
+	'patreon',
+] as const;
+
 export const SocialLinksSchema = () =>
 	z
 		.record(
-			z.enum([
-				'twitter',
-				'mastodon',
-				'github',
-				'gitlab',
-				'bitbucket',
-				'discord',
-				'gitter',
-				'codeberg',
-				'codePen',
-				'youtube',
-				'threads',
-				'linkedin',
-				'twitch',
-				'microsoftTeams',
-				'instagram',
-				'stackOverflow',
-				'x.com',
-				'telegram',
-				'rss',
-				'facebook',
-				'email',
-				'reddit',
-				'patreon',
-			]),
+			z.enum(socialLinks),
 			// Link to the respective social profile for this site
 			z.string().url()
 		)

package/style/util.css

@@ -41,6 +41,12 @@
 		display: block;
 	}
 }
+[data-theme='light'] .light\:sl-hidden {
+	display: none;
+}
+[data-theme='dark'] .dark\:sl-hidden {
+	display: none;
+}
 
 /*
 Flip an element around the y-axis when in an RTL context.

package/translations/gl.json

@@ -0,0 +1,22 @@
+{
+  "skipLink.label": "Ir ao contido",
+  "search.label": "Busca",
+  "search.shortcutLabel": "(Preme / para Busca)",
+  "search.cancelLabel": "Deixar",
+  "search.devWarning": "A busca só está dispoñible nas versións de producción. \nTrata de construir e ollear o sitio para probalo localmente.",
+  "themeSelect.accessibleLabel": "Seleciona tema",
+  "themeSelect.dark": "Escuro",
+  "themeSelect.light": "Claro",
+  "themeSelect.auto": "Auto",
+  "languageSelect.accessibleLabel": "Seleciona linguaxe",
+  "menuButton.accessibleLabel": "Menú",
+  "sidebarNav.accessibleLabel": "Principal",
+  "tableOfContents.onThisPage": "Nesta paxina",
+  "tableOfContents.overview": "Sinopse",
+  "i18n.untranslatedContent": "Este contido aínda non está dispoñible no teu idioma.",
+  "page.editLink": "Editar paxina",
+  "page.lastUpdated": "Última actualización:",
+  "page.previousLink": "Anterior",
+  "page.nextLink": "Seguinte",
+  "404.text": "Paxina non atopada. Comproba a URL ou intenta usar a barra de busca."
+}

package/translations/index.ts

@@ -7,6 +7,7 @@ import ja from './ja.json';
 import pt from './pt.json';
 import fa from './fa.json';
 import fr from './fr.json';
+import gl from './gl.json';
 import he from './he.json';
 import id from './id.json';
 import it from './it.json';
@@ -34,6 +35,7 @@ export default Object.fromEntries(
 		pt,
 		fa,
 		fr,
+		gl,
 		he,
 		id,
 		it,

package/utils/createTranslationSystem.ts

@@ -0,0 +1,79 @@
+import type { i18nSchemaOutput } from '../schemas/i18n';
+import builtinTranslations from '../translations';
+import type { StarlightConfig } from './user-config';
+
+export function createTranslationSystem(
+	userTranslations: Record<string, i18nSchemaOutput>,
+	config: Pick<StarlightConfig, 'defaultLocale' | 'locales'>
+) {
+	/** User-configured default locale. */
+	const defaultLocale = config.defaultLocale?.locale || 'root';
+
+	/** 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]
+	);
+
+	/**
+	 * Generate a utility function that returns UI strings for the given `locale`.
+	 * @param {string | undefined} [locale]
+	 * @example
+	 * const t = useTranslations('en');
+	 * const label = t('search.label'); // => 'Search'
+	 */
+	return function useTranslations(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.pick = (startOfKey: string) =>
+			Object.fromEntries(Object.entries(dictionary).filter(([k]) => k.startsWith(startOfKey)));
+		return t;
+	};
+}
+
+/**
+ * Strips the region subtag from a BCP-47 lang string.
+ * @param {string} [lang]
+ * @example
+ * const lang = stripLangRegion('en-GB'); // => 'en'
+ */
+function stripLangRegion(lang: string) {
+	return lang.replace(/-[a-zA-Z]{2}/, '');
+}
+
+/**
+ * Get the BCP-47 language tag for the given locale.
+ * @param locale Locale string or `undefined` for the root locale.
+ */
+function localeToLang(
+	locale: string | undefined,
+	locales: StarlightConfig['locales'],
+	defaultLocale: StarlightConfig['defaultLocale']
+): string {
+	const lang = locale ? locales?.[locale]?.lang : locales?.root?.lang;
+	const defaultLang = defaultLocale?.lang || defaultLocale?.locale;
+	return lang || defaultLang || 'en';
+}
+
+/** Build a dictionary by layering preferred translation sources. */
+function buildDictionary(
+	base: (typeof builtinTranslations)[string],
+	...dictionaries: (i18nSchemaOutput | undefined)[]
+) {
+	const dictionary = { ...base };
+	// Iterate over alternate dictionaries to avoid overwriting preceding values with `undefined`.
+	for (const dict of dictionaries) {
+		for (const key in dict) {
+			const value = dict[key as keyof typeof dict];
+			if (value) dictionary[key as keyof typeof dict] = value;
+		}
+	}
+	return dictionary;
+}

package/utils/navigation.ts

@@ -30,6 +30,7 @@ interface Group {
 	label: string;
 	entries: (Link | Group)[];
 	collapsed: boolean;
+	badge: Badge | undefined;
 }
 
 export type SidebarEntry = Link | Group;
@@ -75,6 +76,7 @@ function configItemToEntry(
 			label: pickLang(item.translations, localeToLang(locale)) || item.label,
 			entries: item.items.map((i) => configItemToEntry(i, currentPathname, locale, routes)),
 			collapsed: item.collapsed,
+			badge: item.badge,
 		};
 	}
 }
@@ -101,6 +103,7 @@ function groupFromAutogenerateConfig(
 		label: pickLang(item.translations, localeToLang(locale)) || item.label,
 		entries: sidebarFromDir(tree, currentPathname, locale, subgroupCollapsed ?? item.collapsed),
 		collapsed: item.collapsed,
+		badge: item.badge,
 	};
 }
 
@@ -231,6 +234,7 @@ function groupFromDir(
 		label: dirName,
 		entries,
 		collapsed,
+		badge: undefined,
 	};
 }
 

package/utils/route-data.ts

@@ -5,9 +5,10 @@ import config from 'virtual:starlight/user-config';
 import { generateToC, type TocItem } from './generateToC';
 import { getFileCommitDate } from './git';
 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 { ensureTrailingSlash } from './path';
 
 interface PageProps extends Route {
 	headings: MarkdownHeading[];
@@ -79,7 +80,7 @@ function getLastUpdated({ entry, id }: PageProps): Date | undefined {
 	return;
 }
 
-function getEditUrl({ entry, id }: PageProps): URL | undefined {
+function getEditUrl({ entry, id, isFallback }: PageProps): URL | undefined {
 	const { editUrl } = entry.data;
 	// If frontmatter value is false, editing is disabled for this page.
 	if (editUrl === false) return;
@@ -90,8 +91,9 @@ function getEditUrl({ entry, id }: PageProps): URL | undefined {
 		url = editUrl;
 	} else if (config.editLink.baseUrl) {
 		const srcPath = project.srcDir.replace(project.root, '');
+		const filePath = isFallback ? localizedId(id, config.defaultLocale.locale) : id;
 		// If a base URL was added in Starlight config, synthesize the edit URL from it.
-		url = ensureTrailingSlash(config.editLink.baseUrl) + srcPath + 'content/docs/' + id;
+		url = ensureTrailingSlash(config.editLink.baseUrl) + srcPath + 'content/docs/' + filePath;
 	}
 	return url ? new URL(url) : undefined;
 }

package/utils/translations-fs.ts

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import type { i18nSchemaOutput } from '../schemas/i18n';
+import { createTranslationSystem } from './createTranslationSystem';
+import type { StarlightConfig } from './user-config';
+import type { AstroConfig } from 'astro';
+
+/**
+ * Loads and creates a translation system from the file system.
+ * Only for use in integration code.
+ * In modules loaded by Vite/Astro, import [`useTranslations`](./translations.ts) instead.
+ *
+ * @see [`./translations.ts`](./translations.ts)
+ */
+export function createTranslationSystemFromFs(
+	opts: Pick<StarlightConfig, 'defaultLocale' | 'locales'>,
+	{ srcDir }: Pick<AstroConfig, 'srcDir'>
+) {
+	/** All translation data from the i18n collection, keyed by `id`, which matches locale. */
+	let userTranslations: Record<string, i18nSchemaOutput> = {};
+	try {
+		const i18nDir = new URL('content/i18n/', srcDir);
+		// Load the user’s i18n directory
+		const files = fs.readdirSync(i18nDir, 'utf-8');
+		// Load the user’s i18n collection and ignore the error if it doesn’t exist.
+		userTranslations = Object.fromEntries(
+			files
+				.filter((file) => file.endsWith('.json'))
+				.map((file) => {
+					const id = file.slice(0, -5);
+					const data = JSON.parse(fs.readFileSync(new URL(file, i18nDir), 'utf-8'));
+					return [id, data] as const;
+				})
+		);
+	} catch (e: unknown) {
+		if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {
+			// i18nDir doesn’t exist, so we ignore the error.
+		} else {
+			// Other errors may be meaningful, e.g. JSON syntax errors, so should be thrown.
+			throw e;
+		}
+	}
+
+	return createTranslationSystem(userTranslations, opts);
+}

package/utils/translations.ts

@@ -1,13 +1,10 @@
-import { type CollectionEntry, getCollection } from 'astro:content';
+import { getCollection } from 'astro:content';
 import config from 'virtual:starlight/user-config';
-import builtinTranslations from '../translations';
-import { localeToLang } from './slugs';
-
-/** User-configured default locale. */
-const defaultLocale = config.defaultLocale?.locale || 'root';
+import type { i18nSchemaOutput } from '../schemas/i18n';
+import { createTranslationSystem } from './createTranslationSystem';
 
 /** All translation data from the i18n collection, keyed by `id`, which matches locale. */
-let userTranslations: Record<string, CollectionEntry<'i18n'>['data']> = {};
+let userTranslations: Record<string, i18nSchemaOutput> = {};
 try {
 	// Load the user’s i18n collection and ignore the error if it doesn’t exist.
 	userTranslations = Object.fromEntries(
@@ -15,24 +12,6 @@ try {
 	);
 } catch {}
 
-/** 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]
-);
-
-/**
- * Strips the region subtag from a BCP-47 lang string.
- * @param {string} [lang]
- * @example
- * const lang = stripLangRegion('en-GB'); // => 'en'
- */
-export function stripLangRegion(lang: string) {
-	return lang.replace(/-[a-zA-Z]{2}/, '');
-}
-
 /**
  * Generate a utility function that returns UI strings for the given `locale`.
  * @param {string | undefined} [locale]
@@ -40,31 +19,4 @@ export function stripLangRegion(lang: string) {
  * const t = useTranslations('en');
  * const label = t('search.label'); // => 'Search'
  */
-export function useTranslations(locale: string | undefined) {
-	const lang = localeToLang(locale);
-	const dictionary = buildDictionary(
-		defaults,
-		builtinTranslations[lang] || builtinTranslations[stripLangRegion(lang)],
-		userTranslations[lang]
-	);
-	const t = <K extends keyof typeof dictionary>(key: K) => dictionary[key];
-	t.pick = (startOfKey: string) =>
-		Object.fromEntries(Object.entries(dictionary).filter(([k]) => k.startsWith(startOfKey)));
-	return t;
-}
-
-/** Build a dictionary by layering preferred translation sources. */
-function buildDictionary(
-	base: (typeof builtinTranslations)[string],
-	...dictionaries: (CollectionEntry<'i18n'>['data'] | undefined)[]
-) {
-	const dictionary = { ...base };
-	// Iterate over alternate dictionaries to avoid overwriting preceding values with `undefined`.
-	for (const dict of dictionaries) {
-		for (const key in dict) {
-			const value = dict[key as keyof typeof dict];
-			if (value) dictionary[key as keyof typeof dict] = value;
-		}
-	}
-	return dictionary;
-}
+export const useTranslations = createTranslationSystem(userTranslations, config);

package/utils/user-config.ts

@@ -1,6 +1,5 @@
 import { z } from 'astro/zod';
 import { parse as bcpParse, stringify as bcpStringify } from 'bcp-47';
-import { BadgeConfigSchema } from '../schemas/badge';
 import { ComponentConfigSchema } from '../schemas/components';
 import { FaviconSchema } from '../schemas/favicon';
 import { HeadConfigSchema } from '../schemas/head';