@astronox/core 0.1.0 → 0.2.0

package/README.md

@@ -44,6 +44,13 @@ Use the remaining entry points for layouts, patterns, primitives, display
 contracts, configuration, theme, client behavior, data validation, and SEO.
 Deep imports into the physical `src` tree are not part of the public API.
 
+Locale catalogs, localized routing, preference persistence, localized metadata,
+and responsive media presentation are available through the `i18n`, `routing`,
+`seo`, and `display` entry points. Consuming sites provide their own locale
+definitions, translations, route names, product metadata, and assets. Generic
+component labels can extend `defaultCoreMessages` through
+`resolveCoreMessages()` while retaining the English fallback.
+
 ## Local Development
 
 `astronox-core` is the only source of truth. A consuming project may link this
@@ -52,10 +59,12 @@ must always reference a released package version.
 
 The expected workflow is:
 
-1. Implement and commit the generic change in this repository.
-2. Validate it from the relevant linked consumer.
-3. Publish a prerelease or stable package version.
-4. Update consumers through their dependency management workflow.
+1. Keep an exact published version in the consumer manifest and lockfile.
+2. Link the sibling package locally without touching either file with
+   `npm install --no-save --package-lock=false ../astronox-core`.
+3. Implement and validate the generic change through the linked consumer.
+4. Publish a prerelease or stable package version.
+5. Update the exact consumer dependency before deployment.
 
 Do not edit installed package files or copy `src` folders between projects.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [
@@ -35,9 +35,11 @@
     "./config": "./src/config/index.ts",
     "./data": "./src/data/index.ts",
     "./display": "./src/display/index.ts",
+    "./i18n": "./src/i18n/index.ts",
     "./layouts": "./src/layouts/index.ts",
     "./patterns": "./src/patterns/index.ts",
     "./primitives": "./src/primitives/index.ts",
+    "./routing": "./src/routing/index.ts",
     "./seo": "./src/seo/index.ts",
     "./theme": "./src/theme/index.ts",
     "./styles.css": "./src/styles/style.css",

package/src/components/navigation/Breadcrumbs/Breadcrumbs.astro

@@ -2,6 +2,7 @@
 import type { HTMLAttributes } from 'astro/types';
 import type { BreadcrumbItem } from '../../../display/contracts';
 import type { Tone } from '../../../theme/contracts';
+import { defaultCoreMessages } from '../../../i18n/coreMessages';
 
 type Props = HTMLAttributes<'nav'> & {
   items: readonly BreadcrumbItem[];
@@ -13,7 +14,7 @@ const {
   class: className,
   'data-tone': dataTone,
   items,
-  label = "Fil d'Ariane",
+  label = defaultCoreMessages.navigation.breadcrumbs,
   tone,
   ...attrs
 } = Astro.props;

package/src/components/navigation/SubNavigation/SubNavigation.astro

@@ -3,6 +3,7 @@ import type { HTMLAttributes } from 'astro/types';
 import type { Tone } from '../../../theme/contracts';
 import type { SubNavigationItem } from '../navigationTypes';
 import Media from '../../../primitives/media/Media/Media.astro';
+import { defaultCoreMessages } from '../../../i18n/coreMessages';
 
 type Props = HTMLAttributes<'nav'> & {
   items: readonly SubNavigationItem[];
@@ -14,7 +15,7 @@ const {
   class: className,
   'data-tone': dataTone,
   items,
-  label = 'Navigation de section',
+  label = defaultCoreMessages.navigation.section,
   tone,
   ...attrs
 } = Astro.props;

package/src/display/index.ts

@@ -1 +1,2 @@
 export * from './contracts';
+export * from './responsiveMedia';

package/src/display/responsiveMedia.ts

@@ -0,0 +1,38 @@
+import type { DisplayMedia } from './contracts';
+
+export type MediaRendition = Pick<
+  DisplayMedia,
+  'contentBounds' | 'height' | 'src' | 'width'
+>;
+
+export type ResponsiveMediaInput = {
+  alt: string;
+  loading?: DisplayMedia['loading'];
+  renditions: readonly MediaRendition[];
+  sizes: string;
+};
+
+export function presentResponsiveMedia({
+  alt,
+  loading = 'lazy',
+  renditions,
+  sizes,
+}: ResponsiveMediaInput): DisplayMedia {
+  const sortedRenditions = renditions.toSorted(
+    (left, right) => left.width - right.width,
+  );
+  const smallest = sortedRenditions[0];
+  if (!smallest) throw new Error(`Missing media rendition: ${alt}`);
+
+  return {
+    ...smallest,
+    alt,
+    fit: 'contain',
+    loading,
+    sizes,
+    sources: sortedRenditions.map((rendition) => ({
+      src: rendition.src,
+      width: rendition.width,
+    })),
+  };
+}

package/src/i18n/LocalePreferenceBootstrap.astro

@@ -0,0 +1,40 @@
+---
+import type { LocaleDefinition } from './config';
+
+type Props = {
+  defaultLocale: string;
+  locales: readonly LocaleDefinition[];
+  storageKey: string;
+};
+
+const { defaultLocale, locales, storageKey } = Astro.props;
+const localeEntries = locales
+  .filter(({ id }) => id !== defaultLocale)
+  .map(({ id, urlCode }) => [id, urlCode]);
+---
+
+<script
+  is:inline
+  define:vars={{
+    localeEntries,
+    storageKey,
+  }}
+>
+  (() => {
+    if (window.location.pathname !== '/') return;
+
+    try {
+      const preferredLocale = localStorage.getItem(storageKey);
+      const preferredUrlCode = localeEntries.find(
+        ([locale]) => locale === preferredLocale,
+      )?.[1];
+      if (!preferredUrlCode) return;
+
+      window.location.replace(
+        `/${preferredUrlCode}${window.location.search}${window.location.hash}`,
+      );
+    } catch {
+      // The canonical default-locale page remains usable without storage.
+    }
+  })();
+</script>

package/src/i18n/catalog.ts

@@ -0,0 +1,203 @@
+export type MessageTree = {
+  readonly [key: string]: string | MessageTree;
+};
+
+export type MessageShape<T> = {
+  readonly [Key in keyof T]: T[Key] extends string
+    ? string
+    : T[Key] extends MessageTree
+      ? MessageShape<T[Key]>
+      : never;
+};
+
+export type VersionedMessageShape<
+  T extends { readonly schemaVersion: number },
+> = {
+  readonly schemaVersion: T['schemaVersion'];
+} & MessageShape<Omit<T, 'schemaVersion'>>;
+
+export function defineLocalizedCatalog<
+  const TLocale extends string,
+  const TFallbackLocale extends TLocale,
+  const TFallbackCatalog extends MessageTree,
+>({
+  catalogs,
+  fallbackLocale,
+  locales,
+}: {
+  catalogs: Readonly<Record<TLocale, unknown>> &
+    Readonly<Record<TFallbackLocale, TFallbackCatalog>>;
+  fallbackLocale: TFallbackLocale;
+  locales: readonly TLocale[];
+}): Readonly<Record<TLocale, MessageShape<TFallbackCatalog>>> {
+  const fallback = catalogs[fallbackLocale];
+
+  return Object.fromEntries(
+    locales.map((locale) => [
+      locale,
+      resolveLocalizedCatalog(fallback, catalogs[locale], locale),
+    ]),
+  ) as Readonly<Record<TLocale, MessageShape<TFallbackCatalog>>>;
+}
+
+export function resolveLocalizedCatalog<const TFallback extends MessageTree>(
+  fallback: TFallback,
+  translated: unknown,
+  locale: string,
+): MessageShape<TFallback> {
+  return resolveMessageNode(
+    fallback,
+    translated,
+    locale,
+    '',
+  ) as MessageShape<TFallback>;
+}
+
+export function resolveVersionedLocaleCatalog<
+  const TFallback extends { readonly schemaVersion: number },
+>(
+  fallback: TFallback,
+  translated: unknown,
+  locale: string,
+): VersionedMessageShape<TFallback> {
+  if (!isMessageRecord(translated)) {
+    throw new Error(`Invalid ${locale} locale catalog: expected object`);
+  }
+  if (translated.schemaVersion !== fallback.schemaVersion) {
+    throw new Error(
+      `Invalid ${locale} locale schema version: ` +
+        `expected ${fallback.schemaVersion}, received ${String(translated.schemaVersion)}`,
+    );
+  }
+
+  return {
+    schemaVersion: fallback.schemaVersion,
+    ...resolveLocalizedCatalog(
+      stripSchemaVersion(fallback) as MessageTree,
+      stripSchemaVersion(translated),
+      locale,
+    ),
+  } as VersionedMessageShape<TFallback>;
+}
+
+export function formatMessage(
+  template: string,
+  values: Readonly<Record<string, string | number>>,
+): string {
+  const rendered = template.replace(
+    /\{([a-zA-Z][a-zA-Z0-9]*)\}/g,
+    (_, key: string) => {
+      const value = values[key];
+      if (value === undefined) {
+        throw new Error(`Missing localized message value: ${key}`);
+      }
+      return String(value);
+    },
+  );
+
+  if (/\{[^{}]+\}/.test(rendered)) {
+    throw new Error(`Unresolved localized message: ${rendered}`);
+  }
+
+  return rendered;
+}
+
+function resolveMessageNode(
+  fallback: string | MessageTree,
+  translated: unknown,
+  locale: string,
+  path: string,
+): string | MessageTree {
+  if (typeof fallback === 'string') {
+    assertMessage(fallback, 'fallback', path);
+    if (translated === undefined) return fallback;
+    if (typeof translated !== 'string') {
+      throw new Error(
+        `Invalid ${locale} localized value at ${path}: expected string`,
+      );
+    }
+    assertMessage(translated, locale, path);
+    assertPlaceholders(fallback, translated, locale, path);
+    return translated;
+  }
+
+  if (translated !== undefined && !isMessageRecord(translated)) {
+    throw new Error(
+      `Invalid ${locale} localized value at ${path || '<root>'}: expected object`,
+    );
+  }
+
+  const translatedRecord = translated ?? {};
+  const extraKeys = Object.keys(translatedRecord).filter(
+    (key) => !(key in fallback),
+  );
+  if (extraKeys.length > 0) {
+    throw new Error(
+      `Invalid ${locale} localized keys at ${path || '<root>'}: ` +
+        `[${extraKeys.join(', ')}]`,
+    );
+  }
+
+  return Object.fromEntries(
+    Object.entries(fallback).map(([key, fallbackValue]) => {
+      const childPath = path ? `${path}.${key}` : key;
+      return [
+        key,
+        resolveMessageNode(
+          fallbackValue,
+          translatedRecord[key],
+          locale,
+          childPath,
+        ),
+      ];
+    }),
+  );
+}
+
+function isMessageRecord(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+function stripSchemaVersion(
+  value: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([key]) => key !== 'schemaVersion'),
+  );
+}
+
+function assertMessage(value: string, locale: string, path: string): void {
+  if (value.trim().length === 0) {
+    throw new Error(`Empty ${locale} localized value at ${path}`);
+  }
+}
+
+function assertPlaceholders(
+  fallback: string,
+  translated: string,
+  locale: string,
+  path: string,
+): void {
+  const expected = getPlaceholders(fallback);
+  const actual = getPlaceholders(translated);
+  if (
+    expected.length !== actual.length ||
+    expected.some((placeholder, index) => placeholder !== actual[index])
+  ) {
+    throw new Error(
+      `Invalid ${locale} placeholders for ${path}: ` +
+        `expected [${expected.join(', ')}], received [${actual.join(', ')}]`,
+    );
+  }
+}
+
+function getPlaceholders(message: string): readonly string[] {
+  return [...message.matchAll(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g)]
+    .map((match) => match[1]!)
+    .toSorted();
+}

package/src/i18n/config.ts

@@ -0,0 +1,112 @@
+export type TextDirection = 'ltr' | 'rtl';
+
+export type LocaleDefinition = {
+  id: string;
+  urlCode: string;
+  languageTag: string;
+  nativeLabel: string;
+  intlLocale: string;
+  openGraphLocale: string;
+  direction: TextDirection;
+};
+
+export type LocaleConfig<
+  TDefinition extends LocaleDefinition = LocaleDefinition,
+> = {
+  definitions: readonly TDefinition[];
+  locales: readonly TDefinition['id'][];
+  localizedLocales: readonly TDefinition['id'][];
+  defaultLocale: TDefinition['id'];
+  prefixDefaultLocale: boolean;
+  isLocale(value: string): value is TDefinition['id'];
+  getDefinition(locale: TDefinition['id']): TDefinition;
+  getLocaleFromUrlCode(value: string): TDefinition['id'] | undefined;
+  getLocaleFromLanguageTag(value: string): TDefinition['id'] | undefined;
+  requireLocalizedLocale(value: string): TDefinition['id'];
+};
+
+export function createLocaleConfig<
+  const TDefinitions extends readonly [
+    LocaleDefinition,
+    ...LocaleDefinition[],
+  ],
+  const TDefaultLocale extends TDefinitions[number]['id'],
+>({
+  defaultLocale,
+  locales,
+  prefixDefaultLocale = false,
+}: {
+  defaultLocale: TDefaultLocale;
+  locales: TDefinitions;
+  prefixDefaultLocale?: boolean;
+}): LocaleConfig<TDefinitions[number]> & {
+  defaultLocale: TDefaultLocale;
+} {
+  type Definition = TDefinitions[number];
+  type Locale = Definition['id'];
+
+  const localeById = new Map<Locale, Definition>();
+  const localeByUrlCode = new Map<string, Definition>();
+  const localeByLanguageTag = new Map<string, Definition>();
+
+  for (const locale of locales) {
+    if (localeById.has(locale.id)) {
+      throw new Error(`Duplicate locale: ${locale.id}`);
+    }
+
+    const normalizedUrlCode = locale.urlCode.toLowerCase();
+    if (localeByUrlCode.has(normalizedUrlCode)) {
+      throw new Error(`Duplicate locale URL code: ${locale.urlCode}`);
+    }
+
+    const normalizedLanguageTag = locale.languageTag.toLowerCase();
+    if (localeByLanguageTag.has(normalizedLanguageTag)) {
+      throw new Error(`Duplicate locale language tag: ${locale.languageTag}`);
+    }
+
+    localeById.set(locale.id, locale);
+    localeByUrlCode.set(normalizedUrlCode, locale);
+    localeByLanguageTag.set(normalizedLanguageTag, locale);
+  }
+
+  if (!localeById.has(defaultLocale)) {
+    throw new Error(`Unknown default locale: ${defaultLocale}`);
+  }
+
+  const localeIds = locales.map(({ id }) => id);
+  const localizedLocales = localeIds.filter(
+    (locale) => prefixDefaultLocale || locale !== defaultLocale,
+  );
+
+  return {
+    definitions: locales,
+    locales: localeIds,
+    localizedLocales,
+    defaultLocale,
+    prefixDefaultLocale,
+    isLocale(value: string): value is Locale {
+      return localeById.has(value as Locale);
+    },
+    getDefinition(locale: Locale): Definition {
+      const definition = localeById.get(locale);
+      if (!definition) throw new Error(`Unsupported locale: ${locale}`);
+      return definition;
+    },
+    getLocaleFromUrlCode(value: string): Locale | undefined {
+      return localeByUrlCode.get(value.toLowerCase())?.id;
+    },
+    getLocaleFromLanguageTag(value: string): Locale | undefined {
+      return localeByLanguageTag.get(value.toLowerCase())?.id;
+    },
+    requireLocalizedLocale(value: string): Locale {
+      const locale = localeByUrlCode.get(value.toLowerCase())?.id;
+      if (
+        !locale ||
+        (!prefixDefaultLocale && locale === defaultLocale)
+      ) {
+        throw new Error(`Unsupported localized route locale: ${value}`);
+      }
+      return locale;
+    },
+  };
+}

package/src/i18n/coreMessages.ts

@@ -0,0 +1,37 @@
+import {
+  resolveLocalizedCatalog,
+  type MessageShape,
+} from './catalog';
+
+export const defaultCoreMessages = {
+  actions: {
+    close: 'Close',
+    copy: 'Copy',
+    enterFullscreen: 'Enter full screen',
+    exitFullscreen: 'Exit full screen',
+    next: 'Next',
+    open: 'Open',
+    previous: 'Previous',
+    search: 'Search',
+  },
+  feedback: {
+    noResults: 'No results.',
+  },
+  navigation: {
+    breadcrumbs: 'Breadcrumbs',
+    section: 'Section navigation',
+  },
+} as const;
+
+export type CoreMessages = MessageShape<typeof defaultCoreMessages>;
+
+export function resolveCoreMessages(
+  translated: unknown = undefined,
+  locale = 'en',
+): CoreMessages {
+  return resolveLocalizedCatalog(
+    defaultCoreMessages,
+    translated,
+    locale,
+  );
+}

package/src/i18n/formatters.ts

@@ -0,0 +1,34 @@
+export type LocaleFormatters = ReturnType<typeof createLocaleFormatters>;
+
+export function createLocaleFormatters(intlLocale: string) {
+  return {
+    locale: intlLocale,
+    collator: new Intl.Collator(intlLocale, { sensitivity: 'base' }),
+    integer: new Intl.NumberFormat(intlLocale, {
+      maximumFractionDigits: 0,
+    }),
+    decimal: new Intl.NumberFormat(intlLocale, {
+      maximumFractionDigits: 2,
+    }),
+    fixedDecimal: new Intl.NumberFormat(intlLocale, {
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+    }),
+    dateLong: new Intl.DateTimeFormat(intlLocale, {
+      day: 'numeric',
+      month: 'short',
+      year: 'numeric',
+      timeZone: 'UTC',
+    }),
+    dateTimeLong: new Intl.DateTimeFormat(intlLocale, {
+      dateStyle: 'long',
+      timeStyle: 'short',
+      timeZone: 'UTC',
+    }),
+    list: new Intl.ListFormat(intlLocale, {
+      style: 'long',
+      type: 'conjunction',
+    }),
+    plural: new Intl.PluralRules(intlLocale),
+  } as const;
+}

package/src/i18n/index.ts

@@ -0,0 +1,6 @@
+export { default as LocalePreferenceBootstrap } from './LocalePreferenceBootstrap.astro';
+export * from './catalog';
+export * from './config';
+export * from './coreMessages';
+export * from './formatters';
+export * from './preference';

package/src/i18n/preference.ts

@@ -0,0 +1,58 @@
+export type LocalePreferenceControllerOptions<TLocale extends string> = {
+  storageKey: string;
+  resolveLocale(languageTag: string): TLocale | undefined;
+  resolvePath(pathname: string, locale: TLocale): string;
+  initializedAttribute?: string;
+};
+
+export function createLocalePreferenceController<TLocale extends string>({
+  initializedAttribute = 'data-language-preference-initialized',
+  resolveLocale,
+  resolvePath,
+  storageKey,
+}: LocalePreferenceControllerOptions<TLocale>) {
+  return function initLocalePreference(
+    root: Document = document,
+  ): () => void {
+    const element = root.documentElement;
+    if (element.hasAttribute(initializedAttribute)) return () => undefined;
+    element.setAttribute(initializedAttribute, '');
+
+    const handleClick = (event: MouseEvent): void => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+
+      const link = target.closest<HTMLAnchorElement>('a[hreflang]');
+      const languageTag = link?.getAttribute('hreflang');
+      const locale = languageTag
+        ? resolveLocale(languageTag)
+        : undefined;
+      if (!locale) return;
+
+      event.preventDefault();
+      try {
+        localStorage.setItem(storageKey, locale);
+      } catch {
+        // Navigation remains available when storage is unavailable.
+      }
+
+      const destination = new URL(
+        resolvePath(window.location.pathname, locale),
+        window.location.origin,
+      );
+      destination.search = window.location.search;
+      destination.hash = window.location.hash;
+
+      if (destination.href !== window.location.href) {
+        window.location.assign(destination);
+      }
+    };
+
+    root.addEventListener('click', handleClick);
+
+    return () => {
+      root.removeEventListener('click', handleClick);
+      element.removeAttribute(initializedAttribute);
+    };
+  };
+}

package/src/index.ts

@@ -2,5 +2,7 @@ export * from './client/index';
 export * from './config/index';
 export * from './data/index';
 export * from './display/index';
+export * from './i18n/index';
+export * from './routing/index';
 export * from './seo/index';
 export * from './theme/index';

package/src/routing/index.ts

@@ -0,0 +1 @@
+export * from './localized';

package/src/routing/localized.ts

@@ -0,0 +1,155 @@
+import type { LocaleConfig, LocaleDefinition } from '../i18n/config';
+import { normalizePathname } from '../seo/url';
+
+export type LocalizedRoutePolicy = 'localized' | 'technical';
+
+export type LocalizedRouter<TLocale extends string> = {
+  localizePath(path: string, locale: TLocale): string;
+  stripLocalePrefix(path: string): { locale: TLocale; path: string };
+  resolveLocale(path: string): TLocale;
+  getEquivalentPath(path: string, locale: TLocale): string;
+  getRoutePolicy(path: string): LocalizedRoutePolicy;
+  normalizePath(path: string): string;
+};
+
+export function createLocalizedRouter<
+  TDefinition extends LocaleDefinition,
+>({
+  localeConfig,
+  localizedRoots = ['/'],
+  technicalRoots = [],
+}: {
+  localeConfig: LocaleConfig<TDefinition>;
+  localizedRoots?: readonly string[];
+  technicalRoots?: readonly string[];
+}): LocalizedRouter<TDefinition['id']> {
+  type Locale = TDefinition['id'];
+
+  const normalizedLocalizedRoots = localizedRoots.map(normalizePathname);
+  const normalizedTechnicalRoots = technicalRoots.map(normalizePathname);
+
+  const localizePath = (path: string, locale: Locale): string => {
+    const { pathname, suffix } = splitPathReference(path);
+    const normalizedPath = normalizePathname(pathname);
+    if (
+      !localeConfig.prefixDefaultLocale &&
+      locale === localeConfig.defaultLocale
+    ) {
+      return `${normalizedPath}${suffix}`;
+    }
+
+    const prefix = `/${localeConfig.getDefinition(locale).urlCode}`;
+    const localizedPath = normalizedPath === '/'
+      ? prefix
+      : normalizePathname(`${prefix}${normalizedPath}`);
+    return `${localizedPath}${suffix}`;
+  };
+
+  const stripLocalePrefix = (
+    path: string,
+  ): { locale: Locale; path: string } => {
+    const { pathname, suffix } = splitPathReference(path);
+    const normalizedPath = normalizePathname(pathname);
+    const [firstSegment = ''] = normalizedPath.slice(1).split('/');
+    const locale = localeConfig.getLocaleFromUrlCode(firstSegment);
+
+    if (!locale) {
+      return {
+        locale: localeConfig.defaultLocale,
+        path: `${normalizedPath}${suffix}`,
+      };
+    }
+
+    const prefix = `/${firstSegment}`;
+    const unprefixedPath = normalizedPath.slice(prefix.length);
+    return {
+      locale,
+      path: `${normalizePathname(unprefixedPath || '/')}${suffix}`,
+    };
+  };
+
+  const matchesRoot = (path: string, root: string): boolean =>
+    path === root || path.startsWith(`${root}/`);
+
+  const getRoutePolicy = (path: string): LocalizedRoutePolicy => {
+    const { path: unprefixedPath } = stripLocalePrefix(path);
+    const normalizedPath = normalizePathname(unprefixedPath);
+
+    if (
+      normalizedTechnicalRoots.some((root) =>
+        matchesRoot(normalizedPath, root),
+      )
+    ) {
+      return 'technical';
+    }
+
+    return normalizedLocalizedRoots.some(
+      (root) => root === '/' || matchesRoot(normalizedPath, root),
+    )
+      ? 'localized'
+      : 'technical';
+  };
+
+  return {
+    localizePath,
+    stripLocalePrefix,
+    resolveLocale(path: string): Locale {
+      return stripLocalePrefix(path).locale;
+    },
+    getEquivalentPath(path: string, locale: Locale): string {
+      const { path: unprefixedPath } = stripLocalePrefix(path);
+      return getRoutePolicy(unprefixedPath) === 'localized'
+        ? localizePath(unprefixedPath, locale)
+        : unprefixedPath;
+    },
+    getRoutePolicy,
+    normalizePath(path: string): string {
+      const { pathname, suffix } = splitPathReference(path);
+      return `${normalizePathname(pathname)}${suffix}`;
+    },
+  };
+}
+
+export type LocalizedRouteParams = {
+  locale: string;
+};
+
+export function createLocalizedRoutePaths<
+  TDefinition extends LocaleDefinition,
+>(localeConfig: LocaleConfig<TDefinition>): readonly {
+  params: LocalizedRouteParams;
+  props: { locale: TDefinition['id'] };
+}[] {
+  return localeConfig.localizedLocales.map((locale) => ({
+    params: {
+      locale: localeConfig.getDefinition(locale).urlCode,
+    },
+    props: { locale },
+  }));
+}
+
+function splitPathReference(value: string): {
+  pathname: string;
+  suffix: string;
+} {
+  const cleanValue = value.trim();
+
+  if (/^https?:\/\//i.test(cleanValue)) {
+    const url = new URL(cleanValue);
+    return {
+      pathname: url.pathname,
+      suffix: `${url.search}${url.hash}`,
+    };
+  }
+
+  const searchIndex = cleanValue.indexOf('?');
+  const hashIndex = cleanValue.indexOf('#');
+  const suffixIndex = [searchIndex, hashIndex]
+    .filter((index) => index >= 0)
+    .reduce((lowest, index) => Math.min(lowest, index), cleanValue.length);
+
+  return {
+    pathname: cleanValue.slice(0, suffixIndex),
+    suffix: cleanValue.slice(suffixIndex),
+  };
+}

package/src/seo/index.ts

@@ -1,5 +1,6 @@
 export { default as StaticRedirect } from './StaticRedirect.astro';
 export * from './pageSeo';
+export * from './localizedMeta';
 export * from './robots';
 export * from './sitemap';
 export * from './structuredData';

package/src/seo/localizedMeta.ts

@@ -0,0 +1,58 @@
+import type { PageMeta } from '../config/pageMeta';
+import type { LocaleConfig, LocaleDefinition } from '../i18n/config';
+import type { LocalizedRouter } from '../routing/localized';
+import { normalizePathname } from './url';
+
+export type LocalizedMetaInput = Omit<
+  PageMeta,
+  | 'alternates'
+  | 'canonical'
+  | 'lang'
+  | 'openGraphLocale'
+  | 'openGraphLocaleAlternates'
+> & {
+  canonical: string;
+};
+
+export function createLocalizedPageMeta<
+  TDefinition extends LocaleDefinition,
+>({
+  input,
+  locale,
+  localeConfig,
+  router,
+  socialImageAlt,
+}: {
+  input: LocalizedMetaInput;
+  locale: TDefinition['id'];
+  localeConfig: LocaleConfig<TDefinition>;
+  router: LocalizedRouter<TDefinition['id']>;
+  socialImageAlt?: string;
+}): PageMeta {
+  const definition = localeConfig.getDefinition(locale);
+  const { path } = router.stripLocalePrefix(
+    normalizePathname(input.canonical),
+  );
+  const alternates = localeConfig.definitions.map((alternateLocale) => ({
+    lang: alternateLocale.languageTag,
+    href: router.localizePath(path, alternateLocale.id),
+  }));
+
+  return {
+    ...input,
+    canonical: router.localizePath(path, locale),
+    lang: definition.languageTag,
+    socialImageAlt: input.socialImageAlt ?? socialImageAlt,
+    openGraphLocale: definition.openGraphLocale,
+    openGraphLocaleAlternates: localeConfig.definitions
+      .filter((alternateLocale) => alternateLocale.id !== locale)
+      .map((alternateLocale) => alternateLocale.openGraphLocale),
+    alternates: [
+      ...alternates,
+      {
+        lang: 'x-default',
+        href: router.localizePath(path, localeConfig.defaultLocale),
+      },
+    ],
+  };
+}