@koehler8/cms 1.0.0-beta.18 → 1.0.0-beta.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.18",
+  "version": "1.0.0-beta.19",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",

package/src/components/Home.vue

@@ -90,7 +90,7 @@ const {
   attemptUnlock,
 } = useDraftGate({ siteData, currentPage });
 
-usePageMeta({ siteData, currentPage });
+usePageMeta({ siteData, currentPage, locale: () => props.locale });
 
 const {
   isComingSoonVisible,

package/src/composables/usePageMeta.js

@@ -1,6 +1,8 @@
 import { computed } from 'vue';
 import { useHead } from '@unhead/vue';
 import { isPathDraft } from '../utils/draftMode.js';
+import { buildCanonicalUrl } from '../utils/canonicalUrl.js';
+import { availableLocales as configAvailableLocales, baseLocale as configBaseLocale } from '../utils/loadConfig.js';
 
 const SPECIAL_PAGE_LABELS = {
   home: '',
@@ -36,9 +38,15 @@ function inferPageLabel(page) {
     .join(' / ');
 }
 
-export function usePageMeta({ siteData, currentPage }) {
+export function usePageMeta({ siteData, currentPage, locale }) {
   const siteTitle = computed(() => siteData.value?.site?.title || '');
   const siteDescription = computed(() => siteData.value?.site?.description || '');
+  const siteUrl = computed(() => siteData.value?.site?.url || '');
+  const localeValue = computed(() => {
+    if (typeof locale === 'function') return locale() || '';
+    if (typeof locale === 'string') return locale;
+    return '';
+  });
 
   const isDraft = computed(() =>
     isPathDraft(siteData.value, currentPage.value?.path, currentPage.value),
@@ -76,6 +84,54 @@ export function usePageMeta({ siteData, currentPage }) {
     return siteDescription.value || '';
   });
 
+  // Canonical URL — base-locale URLs have no prefix; non-base locales get
+  // /{locale}/path. Drafts skip canonical (gated content shouldn't advertise
+  // an authoritative URL). Sites without a configured site.url skip too —
+  // we can't build an absolute URL.
+  const canonicalHref = computed(() => {
+    if (isDraft.value) return '';
+    if (!siteUrl.value) return '';
+    return buildCanonicalUrl({
+      siteUrl: siteUrl.value,
+      locale: localeValue.value,
+      baseLocale: configBaseLocale,
+      path: currentPage.value?.path || '/',
+    });
+  });
+
+  // hreflang alternates — only emitted when a site has more than one
+  // locale's content on disk. Includes one entry per available locale plus
+  // an `x-default` pointing at the base-locale URL (Google's preferred
+  // pattern for sites without explicit geo-targeting).
+  const hreflangLinks = computed(() => {
+    if (isDraft.value) return [];
+    if (!siteUrl.value) return [];
+    if (!Array.isArray(configAvailableLocales) || configAvailableLocales.length <= 1) return [];
+    const path = currentPage.value?.path || '/';
+    const links = [];
+    for (const code of configAvailableLocales) {
+      const href = buildCanonicalUrl({
+        siteUrl: siteUrl.value,
+        locale: code,
+        baseLocale: configBaseLocale,
+        path,
+      });
+      if (href) {
+        links.push({ rel: 'alternate', hreflang: code, href, key: `hreflang-${code}` });
+      }
+    }
+    const defaultHref = buildCanonicalUrl({
+      siteUrl: siteUrl.value,
+      locale: configBaseLocale,
+      baseLocale: configBaseLocale,
+      path,
+    });
+    if (defaultHref) {
+      links.push({ rel: 'alternate', hreflang: 'x-default', href: defaultHref, key: 'hreflang-x-default' });
+    }
+    return links;
+  });
+
   useHead(() => {
     const description = pageMetaDescription.value;
     const meta = [];
@@ -85,11 +141,19 @@ export function usePageMeta({ siteData, currentPage }) {
     if (isDraft.value) {
       meta.push({ name: 'robots', content: 'noindex, nofollow', key: 'robots' });
     }
+    const link = [];
+    if (canonicalHref.value) {
+      link.push({ rel: 'canonical', href: canonicalHref.value, key: 'canonical' });
+    }
+    for (const entry of hreflangLinks.value) {
+      link.push(entry);
+    }
     return {
       title: pageMetaTitle.value,
       meta,
+      link,
     };
   });
 
-  return { pageMetaTitle, pageMetaDescription, isDraft };
+  return { pageMetaTitle, pageMetaDescription, isDraft, canonicalHref, hreflangLinks };
 }

package/src/router/index.js

@@ -3,7 +3,7 @@ import { h } from 'vue';
 
 import Home from '../components/Home.vue';
 
-import { SUPPORTED_LOCALES } from '../constants/locales.js';
+import { availableLocales, baseLocale } from '../utils/loadConfig.js';
 
 const LocaleLayout = {
   name: 'LocaleLayout',
@@ -12,57 +12,85 @@ const LocaleLayout = {
   },
 };
 
-export const routes = [
-  {
+// Locales that should match the `/:locale/...` route — every available
+// locale on disk EXCEPT the base. The base locale is served at the
+// unprefixed path; emitting `/{baseLocale}/path` would be a duplicate URL.
+//
+// Read at module-load time. The vite-plugin's generated entry calls
+// setConfigLoader() synchronously before importing the app, so by the
+// time this module is evaluated (inside main.js), the singletons are
+// populated.
+function computeLocalePrefixes() {
+  if (!Array.isArray(availableLocales)) return [];
+  return availableLocales.filter((l) => typeof l === 'string' && l !== baseLocale);
+}
+
+export function buildRoutes(localePrefixes = computeLocalePrefixes()) {
+  const homeRoute = {
     path: '/',
     name: 'Home',
     component: Home,
     props: { pageId: 'home', pagePath: '/' },
-  },
-  {
-    path: `/:locale(${SUPPORTED_LOCALES.join('|')})`,
-    component: LocaleLayout,
-    children: [
-      {
-        path: '',
-        name: 'HomeLocale',
-        component: Home,
-        props: (route) => ({ pageId: 'home', pagePath: '/', locale: route.params.locale }),
-      },
-      {
-        path: ':pathMatch(.*)*',
-        name: 'LocaleDynamicPage',
-        component: Home,
-        props: (route) => {
-          const pathMatch = route.params.pathMatch;
-          const slugSegments = Array.isArray(pathMatch) ? pathMatch : [pathMatch || ''];
-          const rawSlug = `/${slugSegments.filter(Boolean).join('/')}`;
-          const normalizedSlug = rawSlug.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
-          return { pagePath: normalizedSlug, locale: route.params.locale };
-        },
-      },
-    ],
-  },
-  {
+  };
+
+  const catchAllRoute = {
     path: '/:pathMatch(.*)*',
     name: 'DynamicPage',
     component: Home,
     props: (route) => ({ pagePath: route.path || '/' }),
-  },
-];
+  };
+
+  if (!localePrefixes.length) {
+    // Single-locale site: don't register the locale-prefixed route at all.
+    // `/de/about` etc. fall into the catch-all → DynamicPage with a
+    // pagePath that won't match any page → home fallback.
+    return [homeRoute, catchAllRoute];
+  }
+
+  return [
+    homeRoute,
+    {
+      path: `/:locale(${localePrefixes.join('|')})`,
+      component: LocaleLayout,
+      children: [
+        {
+          path: '',
+          name: 'HomeLocale',
+          component: Home,
+          props: (route) => ({ pageId: 'home', pagePath: '/', locale: route.params.locale }),
+        },
+        {
+          path: ':pathMatch(.*)*',
+          name: 'LocaleDynamicPage',
+          component: Home,
+          props: (route) => {
+            const pathMatch = route.params.pathMatch;
+            const slugSegments = Array.isArray(pathMatch) ? pathMatch : [pathMatch || ''];
+            const rawSlug = `/${slugSegments.filter(Boolean).join('/')}`;
+            const normalizedSlug = rawSlug.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+            return { pagePath: normalizedSlug, locale: route.params.locale };
+          },
+        },
+      ],
+    },
+    catchAllRoute,
+  ];
+}
+
+export const routes = buildRoutes();
 
 function normalizeLocale(value = '') {
   return value.toLowerCase().split('-')[0];
 }
 
-export function applyRouterGuards(router) {
+export function applyRouterGuards(router, localePrefixes = computeLocalePrefixes()) {
   router.beforeEach((to) => {
     const rawLocale = (to.params.locale || '').toString().trim();
 
     if (rawLocale) {
       const normalized = normalizeLocale(rawLocale);
 
-      if (!SUPPORTED_LOCALES.includes(normalized)) {
+      if (!localePrefixes.includes(normalized)) {
         return { path: '/', replace: true };
       }
 
@@ -87,7 +115,7 @@ export function applyRouterGuards(router) {
       const navLang = (navigator.language || navigator.userLanguage || '').toString();
       const shortLang = normalizeLocale(navLang || '');
 
-      if (to.path === '/' && SUPPORTED_LOCALES.includes(shortLang)) {
+      if (to.path === '/' && localePrefixes.includes(shortLang)) {
         return { path: `/${shortLang}`, replace: true };
       }
     }

package/src/utils/canonicalUrl.js

@@ -0,0 +1,44 @@
+/**
+ * Single source of truth for the canonical URL formula.
+ *
+ * Used by:
+ *   - usePageMeta.js (emits <link rel="canonical"> + <link rel="alternate" hreflang>)
+ *   - sitemapGenerator.js (emits <loc> + <xhtml:link rel="alternate" hreflang>)
+ *
+ * URL space rule (matches Google / Stripe / GitHub conventions):
+ *   - Base locale → ${siteUrl}${path}     e.g. https://example.com/about
+ *   - Non-base    → ${siteUrl}/${locale}${path}   e.g. https://example.com/de/about
+ *
+ * Returns '' when siteUrl is missing — sitemaps require absolute URLs and
+ * canonical links without a host are useless. Callers treat '' as "skip".
+ */
+
+function normalizePath(value) {
+  if (typeof value !== 'string') return '/';
+  const trimmed = value.trim();
+  if (!trimmed) return '/';
+  let p = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  p = p.replace(/\/+/g, '/').replace(/\/+$/, '');
+  return p || '/';
+}
+
+function normalizeLocale(value) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim().toLowerCase();
+  return trimmed;
+}
+
+export function buildCanonicalUrl({ siteUrl, locale, baseLocale, path } = {}) {
+  const host = typeof siteUrl === 'string' ? siteUrl.trim().replace(/\/+$/, '') : '';
+  if (!host) return '';
+
+  const normalizedPath = normalizePath(path);
+  const loc = normalizeLocale(locale);
+  const base = normalizeLocale(baseLocale);
+
+  if (!loc || loc === base) {
+    return normalizedPath === '/' ? `${host}/` : `${host}${normalizedPath}`;
+  }
+
+  return normalizedPath === '/' ? `${host}/${loc}` : `${host}/${loc}${normalizedPath}`;
+}

package/src/utils/loadConfig.js

@@ -307,13 +307,16 @@ let _loadConfigData = async () => {
 };
 
 let _availableLocales = [];
+let _baseLocale = '';
 
 export function setConfigLoader(instance) {
   if (!instance) return;
   _loadConfigData = instance.loadConfigData;
   _availableLocales = instance.availableLocales || [];
+  _baseLocale = typeof instance.baseLocale === 'string' ? instance.baseLocale : '';
 }
 
 export { _availableLocales as availableLocales };
+export { _baseLocale as baseLocale };
 
 export const loadConfigData = (...args) => _loadConfigData(...args);

package/src/utils/sitemapGenerator.js

@@ -5,12 +5,14 @@
  * sitemap. Returns '' when site.url is missing (the sitemap protocol requires
  * absolute URLs); the plugin treats empty output as "do not write the file."
  *
- * v1 emits only <loc> per page. No <lastmod>, <changefreq>, <priority>, or
- * hreflang alternates yet — a page with a path is listed once with its
- * unprefixed canonical URL. Multi-locale sites can layer hreflang in later.
+ * Single-locale sites emit only <loc> per page. Multi-locale sites add
+ * <xhtml:link rel="alternate" hreflang="..." /> annotations per page (one
+ * per available locale plus an `x-default` pointing at the base-locale
+ * URL). The single-locale output stays byte-identical to pre-hreflang.
  */
 
 import { isPathDraft, normalizeDraftPath } from './draftMode.js';
+import { buildCanonicalUrl } from './canonicalUrl.js';
 
 function escapeXml(value) {
   return String(value).replace(/[<>&'"]/g, (c) => ({
@@ -22,7 +24,7 @@ function escapeXml(value) {
   }[c]));
 }
 
-export function buildSitemap(siteConfig) {
+export function buildSitemap(siteConfig, options = {}) {
   const siteUrl = (siteConfig?.site?.url || '').trim().replace(/\/+$/, '');
   if (!siteUrl) return '';
 
@@ -33,26 +35,61 @@ export function buildSitemap(siteConfig) {
   // the runtime gate; it is not advertised to crawlers.
   if (siteConfig?.site?.draft === true) return '';
 
+  const baseLocale = typeof options.baseLocale === 'string' ? options.baseLocale.toLowerCase() : '';
+  const availableLocales = Array.isArray(options.availableLocales)
+    ? options.availableLocales.map((l) => (typeof l === 'string' ? l.toLowerCase() : '')).filter(Boolean)
+    : [];
+  const isMultiLocale = availableLocales.length > 1;
+
   const pages = siteConfig?.pages || {};
-  const urls = new Set();
+  const entries = [];
+  const seenPaths = new Set();
 
   for (const [, pageData] of Object.entries(pages)) {
     if (!pageData || typeof pageData !== 'object') continue;
-    const path = normalizeDraftPath(pageData.path) || '/';
-    if (isPathDraft(siteConfig, path, pageData)) continue;
-    const url = path === '/' ? `${siteUrl}/` : `${siteUrl}${path}`;
-    urls.add(url);
+    const pagePath = normalizeDraftPath(pageData.path) || '/';
+    if (isPathDraft(siteConfig, pagePath, pageData)) continue;
+    if (seenPaths.has(pagePath)) continue;
+    seenPaths.add(pagePath);
+
+    const baseUrl = buildCanonicalUrl({ siteUrl, baseLocale, locale: baseLocale, path: pagePath });
+    if (!baseUrl) continue;
+
+    const alternates = isMultiLocale
+      ? availableLocales.map((loc) => ({
+          hreflang: loc,
+          href: buildCanonicalUrl({ siteUrl, baseLocale, locale: loc, path: pagePath }),
+        }))
+      : [];
+    if (isMultiLocale) {
+      alternates.push({ hreflang: 'x-default', href: baseUrl });
+    }
+
+    entries.push({ loc: baseUrl, alternates });
   }
 
-  if (urls.size === 0) return '';
+  if (entries.length === 0) return '';
+
+  entries.sort((a, b) => a.loc.localeCompare(b.loc));
+
+  const urlsetAttrs = isMultiLocale
+    ? 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml"'
+    : 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"';
+
+  const renderUrlEntry = (entry) => {
+    if (entry.alternates.length === 0) {
+      return `  <url><loc>${escapeXml(entry.loc)}</loc></url>`;
+    }
+    const altLines = entry.alternates
+      .map((a) => `    <xhtml:link rel="alternate" hreflang="${escapeXml(a.hreflang)}" href="${escapeXml(a.href)}"/>`)
+      .join('\n');
+    return `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>\n${altLines}\n  </url>`;
+  };
 
-  const sortedUrls = Array.from(urls).sort();
-  const urlEntries = sortedUrls
-    .map((loc) => `  <url><loc>${escapeXml(loc)}</loc></url>`)
-    .join('\n');
+  const urlEntries = entries.map(renderUrlEntry).join('\n');
 
   return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<urlset ${urlsetAttrs}>
 ${urlEntries}
 </urlset>
 `;

package/vite-plugin.js

@@ -12,7 +12,6 @@ import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import vue from '@vitejs/plugin-vue';
 
-import { SUPPORTED_LOCALES } from './src/constants/locales.js';
 import { inflateFlatConfig } from './src/utils/inflateFlatConfig.js';
 import { buildRobotsTxt } from './src/utils/robotsGenerator.js';
 import { buildSitemap, getSitemapUrl } from './src/utils/sitemapGenerator.js';
@@ -321,16 +320,22 @@ export default function cmsPlugin(options = {}) {
   const {
     siteDir: siteDirOption = './site',
     frameworkRoot: frameworkRootOption = __dirname,
-    locales = SUPPORTED_LOCALES,
     themes: themePackages = [],
     extensions: extensionPackages = [],
   } = options;
+  // The previous `locales` option is no longer accepted: per-site available
+  // locales are now discovered from on-disk content directories. Passing
+  // `locales` is silently ignored (kept here as a destructure to swallow it
+  // gracefully; the `SUPPORTED_LOCALES` constant remains exported only for
+  // any consumer that imports it directly).
 
   // These are resolved relative to the project cwd at config time
   let siteDir;
   let siteRoot; // project root — parent of siteDir
   let frameworkRoot;
   let siteConfig;
+  let baseLocale = 'en';
+  let availableLocales = [];
   let pagePaths;
   let metadata;
   let tempIndexPath;
@@ -399,7 +404,7 @@ export default function cmsPlugin(options = {}) {
     const sitePublicDir = path.join(siteRoot, 'public');
     fs.mkdirSync(sitePublicDir, { recursive: true });
 
-    const sitemapXml = buildSitemap(siteConfig);
+    const sitemapXml = buildSitemap(siteConfig, { availableLocales, baseLocale });
     const sitemapPath = path.join(sitePublicDir, 'sitemap.xml');
     if (sitemapXml) {
       fs.writeFileSync(sitemapPath, sitemapXml, 'utf-8');
@@ -435,12 +440,24 @@ export default function cmsPlugin(options = {}) {
       const contentConfig = fs.existsSync(contentConfigPath)
         ? JSON.parse(fs.readFileSync(contentConfigPath, 'utf-8'))
         : {};
-      const baseLocale = contentConfig.baseLocale || 'en';
+      baseLocale = contentConfig.baseLocale || 'en';
       const configDir = path.join(contentDir, baseLocale);
       siteConfig = loadSplitConfig(configDir);
       if (!siteConfig) {
         throw new Error(`[@koehler8/cms] site config not found at ${configDir}`);
       }
+      // Discover locales actually present on disk: directories under
+      // content/ that contain a site.json. This becomes the authoritative
+      // list for both the SSG route fanout and the runtime locale-aware
+      // canonical/hreflang emission.
+      availableLocales = fs.existsSync(contentDir)
+        ? fs
+            .readdirSync(contentDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .filter((name) => fs.existsSync(path.join(contentDir, name, 'site.json')))
+            .sort()
+        : [];
       pagePaths = collectPagePaths(siteConfig);
       metadata = extractSiteMetadata(siteConfig);
 
@@ -525,8 +542,14 @@ export default function cmsPlugin(options = {}) {
             const staticRoutes = new Set(['/admin']);
             pagePaths.forEach((routePath) => staticRoutes.add(routePath));
 
+            // Pre-render every page under each non-base locale prefix that
+            // actually has a content directory on disk. The base locale is
+            // served at the unprefixed path (it's already covered by
+            // staticRoutes) — emitting `/{baseLocale}/path` would create
+            // duplicate URLs that all render the same content.
+            const localePrefixes = availableLocales.filter((l) => l !== baseLocale);
             const localizedRoutes = new Set();
-            locales.forEach((locale) => {
+            localePrefixes.forEach((locale) => {
               pagePaths.forEach((routePath) => {
                 const localized =
                   routePath === '/' ? `/${locale}` : `/${locale}${routePath}`;
@@ -620,7 +643,12 @@ const loader = createConfigLoader(allModules);
 export const loadConfigData = loader.loadConfigData;
 export const mergeConfigTrees = loader.mergeConfigTrees;
 export const cloneConfig = loader.cloneConfig;
-export const availableLocales = loader.availableLocales;
+// availableLocales + baseLocale are emitted as build-time literals derived
+// from the same on-disk discovery the plugin uses for SSG includedRoutes
+// and sitemap generation. This guarantees the runtime sees the exact same
+// locale list as the build, regardless of glob-based heuristics.
+export const availableLocales = ${JSON.stringify(availableLocales)};
+export const baseLocale = ${JSON.stringify(baseLocale)};
 `;
       }