init commit for iPAL-kit plugin

src/modules/seo/hreflang.ts

@@ -0,0 +1,55 @@
+import type { I18nConfig, LocalizedSlugs } from '../i18n/index.js'
+
+import { buildLocalizedPath, getLocaleCodes } from '../i18n/index.js'
+
+type BuildHreflangArgs = {
+  /** Absolute site origin, e.g. 'https://example.com'. Omit for relative paths. */
+  baseUrl?: string
+  config: I18nConfig
+  /** Home slug that collapses to the locale root. Defaults to 'home'. */
+  homeSlug?: string
+  /**
+   * Localized segment the document lives under (an archive page's slugs),
+   * e.g. { pl: 'artykuly', en: 'articles' }. Locales missing from the prefix
+   * are omitted — an entry with no archive in that language has no URL there.
+   */
+  prefix?: LocalizedSlugs
+  /** slug per locale for the current document, e.g. { pl: 'o-nas', en: 'about' } */
+  slugs: LocalizedSlugs
+}
+
+/**
+ * Builds a map of locale → URL for hreflang alternate links, suitable for
+ * Next.js Metadata `alternates.languages`.
+ *
+ * Bridges SEO and i18n: for each configured locale that the document has a
+ * slug in, it produces the locale-aware path (via buildLocalizedPath),
+ * optionally prefixed with an absolute origin.
+ *
+ * @example
+ * buildHreflangAlternates({
+ *   slugs: { pl: 'o-nas', en: 'about' },
+ *   config,
+ *   baseUrl: 'https://example.com',
+ * })
+ * // → { pl: 'https://example.com/pl/o-nas', en: 'https://example.com/en/about' }
+ */
+export function buildHreflangAlternates({
+  baseUrl,
+  config,
+  homeSlug = 'home',
+  prefix,
+  slugs,
+}: BuildHreflangArgs): Record<string, string> {
+  const origin = baseUrl?.replace(/\/$/, '') ?? ''
+  const alternates: Record<string, string> = {}
+
+  for (const locale of getLocaleCodes(config)) {
+    const path = buildLocalizedPath({ config, homeSlug, locale, prefix, slugs })
+    if (path) {
+      alternates[locale] = `${origin}${path}`
+    }
+  }
+
+  return alternates
+}