fimo 0.16.0 → 0.18.0

package/dist/scripts/validate-route-metadata.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { pageSourceParamExpressions } from '@fimo/api-contracts';
+import { FIMO_LOCALE_PARAM, resolveRouteContract } from '../runtime/routes/contract.js';
 import { resolveFimoConfigPath } from '../runtime/shared/fimo-config.server.js';
 import { parseRoutesSource } from './lib/parse-routes-file.js';
 function readJson(filePath) {
@@ -10,20 +12,15 @@ function readJson(filePath) {
         return {};
     }
 }
-function getParamNamesFromPath(routePath) {
-    const normalized = routePath === '/' ? '/' : routePath.replace(/\/+$/, '');
-    const segments = normalized.split('/').filter(Boolean);
-    return segments.filter((segment) => segment.startsWith(':')).map((segment) => segment.slice(1));
-}
 function loadConfigRoutes(config) {
     const configRoutes = config.routes ?? {};
     return Object.entries(configRoutes).map(([id, route]) => ({
         id,
         path: route.path ?? '/',
         label: route.label ?? null,
-        paramNames: getParamNamesFromPath(route.path ?? '/'),
-        params: route.params ?? null,
+        sources: route.sources ?? null,
         seo: route.seo ?? null,
+        contract: resolveRouteContract(id, route),
     }));
 }
 export function validateRouteMetadata(options = {}) {
@@ -47,26 +44,26 @@ export function validateRouteMetadata(options = {}) {
     const pathToFile = new Map();
     for (const fr of fileRoutes) {
         if (fr.path && fr.file) {
-            pathToFile.set(fr.path, fr.file);
+            pathToFile.set(normalizeLocaleSpelling(fr.path), fr.file);
         }
     }
     const i18n = validateI18nConfig(config);
     errors.push(...i18n.errors);
     const configRoutes = loadConfigRoutes(config);
     // Cross-validate: non-layout routes in routes.ts should have matching fimo-config entries
-    const configPaths = new Set(configRoutes.map((r) => r.path));
+    const configPaths = new Set(configRoutes.flatMap(registrablePaths));
     for (const fileRoute of fileRoutes) {
         if (fileRoute.isLayout) {
             continue;
         }
-        if (fileRoute.path && !configPaths.has(fileRoute.path)) {
+        if (fileRoute.path && !configPaths.has(normalizeLocaleSpelling(fileRoute.path))) {
             errors.push(`Route with path "${fileRoute.path}" (file: "${fileRoute.file}") exists in src/routes.ts but has no matching entry in ${configDisplayPath}.\nFix: add a route entry to ${configDisplayPath} "routes" with a matching "path".`);
         }
     }
     // Cross-validate: fimo-config routes should have matching routes.ts entries
-    const filePaths = new Set(fileRoutes.filter((r) => !r.isLayout && r.path).map((r) => r.path));
+    const filePaths = new Set(fileRoutes.filter((r) => !r.isLayout && r.path).map((r) => normalizeLocaleSpelling(r.path)));
     for (const route of configRoutes) {
-        if (!filePaths.has(route.path)) {
+        if (!registrablePaths(route).some((candidate) => filePaths.has(candidate))) {
             errors.push(`Route "${route.id}" (${route.path}) exists in ${configDisplayPath} but is not registered in src/routes.ts.\nFix: add the route to src/routes.ts. Example: route('${route.path.replace(/^\//, '')}', './pages/YourPage.tsx')`);
         }
     }
@@ -76,7 +73,7 @@ export function validateRouteMetadata(options = {}) {
             fileRoutes,
             i18n,
             configDisplayPath,
-            routesSourceUsesFimoRoutes: sourceUsesFimoRoutes(fileRoutes, routesFilePath),
+            routesSourceUsesLegacyHelper: sourceUsesLegacyFimoRoutes(routesFilePath),
         }));
     }
     const routeById = new Map();
@@ -88,9 +85,18 @@ export function validateRouteMetadata(options = {}) {
         }
         routeById.set(route.id, route);
     }
+    for (const route of configRoutes) {
+        for (const issue of route.contract.issues) {
+            errors.push(`Route "${route.id}" (${route.path}): ${issue.message}\nFix: ${issue.fix}`);
+        }
+        errors.push(...validatePageSources(route));
+    }
+    errors.push(...validateRouteShapeCollisions(configRoutes));
     // Validate route modules (exports, loaders, meta)
     for (const route of configRoutes) {
-        const file = pathToFile.get(route.path);
+        const file = registrablePaths(route)
+            .map((candidate) => pathToFile.get(candidate))
+            .find(Boolean);
         if (!file) {
             continue;
         }
@@ -99,22 +105,6 @@ export function validateRouteMetadata(options = {}) {
             errors.push(`Route "${route.id}" (${route.path}) references missing module "${file}".\nFix: create the file at src/${file}.`);
             continue;
         }
-        if (route.paramNames.length > 0) {
-            if (!route.params) {
-                errors.push(`Dynamic route "${route.id}" (${route.path}) needs \`params\` metadata to generate prerender URLs.\nFix: add to the route in ${configDisplayPath}: \`"params": { "${route.paramNames[0] || 'param'}": { "schema": "SchemaName", "queryField": "${route.paramNames[0] || 'slug'}", "displayField": "title" } }\``);
-            }
-            else {
-                for (const paramName of route.paramNames) {
-                    const paramInfo = route.params[paramName];
-                    if (!paramInfo || typeof paramInfo !== 'object') {
-                        errors.push(`Dynamic route "${route.id}" (${route.path}): param "${paramName}" must be an object with "schema" and "queryField".\nFix: \`"params": { "${paramName}": { "schema": "SchemaName", "queryField": "${paramName}" } }\``);
-                    }
-                    else if (!paramInfo.schema || !paramInfo.queryField) {
-                        errors.push(`Dynamic route "${route.id}" (${route.path}): param "${paramName}" is missing ${!paramInfo.schema ? '"schema"' : '"queryField"'}.\nFix: \`"${paramName}": { "schema": "SchemaName", "queryField": "${paramName}" }\``);
-                    }
-                }
-            }
-        }
         if (route.seo) {
             const GLOBAL_VARIABLES = new Set(['siteName', 'label']);
             const seoFields = [
@@ -132,15 +122,17 @@ export function validateRouteMetadata(options = {}) {
                     if (GLOBAL_VARIABLES.has(variable)) {
                         continue;
                     }
+                    // Only entry params carry data a template can read; the locale
+                    // segment resolves to a tag, never to an entry.
+                    const entryParamNames = route.contract.entryParams.map((param) => param.name);
+                    const availableParams = entryParamNames.length > 0 ? entryParamNames.join(', ') : 'none';
                     if (variable.includes('.')) {
                         const paramKey = variable.split('.')[0];
-                        if (!route.params || !route.params[paramKey]) {
-                            const availableParams = route.params ? Object.keys(route.params).join(', ') : 'none';
-                            errors.push(`Route "${route.id}" (${route.path}): SEO ${field.name} references "{{${variable}}}" but "${paramKey}" is not a declared param. Available params: ${availableParams}.`);
+                        if (!entryParamNames.includes(paramKey)) {
+                            errors.push(`Route "${route.id}" (${route.path}): SEO ${field.name} references "{{${variable}}}" but "${paramKey}" is not a declared entry param. Available params: ${availableParams}.`);
                         }
                     }
                     else {
-                        const availableParams = route.params ? Object.keys(route.params).join(', ') : 'none';
                         errors.push(`Route "${route.id}" (${route.path}): SEO ${field.name} references "{{${variable}}}" which is not a global variable (siteName, label) and not a dotted param reference (e.g., "{{param.field}}"). Available params: ${availableParams}.`);
                     }
                 }
@@ -149,6 +141,52 @@ export function validateRouteMetadata(options = {}) {
     }
     return { errors, routesChecked: configRoutes.length };
 }
+function validatePageSources(route) {
+    if (!route.sources) {
+        return [];
+    }
+    const errors = [];
+    const entryParamNames = new Set(route.contract.entryParams.map((param) => param.name));
+    for (const [sourceName, rawSource] of Object.entries(route.sources)) {
+        if (!/^[A-Za-z][\w-]*$/.test(sourceName) || !isRecord(rawSource)) {
+            errors.push(`Route "${route.id}" (${route.path}): source "${sourceName}" is not a valid named source.`);
+            continue;
+        }
+        if (rawSource.type === 'labels') {
+            const match = rawSource.match;
+            if (!Array.isArray(match) ||
+                match.length === 0 ||
+                match.some((pattern) => {
+                    if (typeof pattern !== 'string')
+                        return true;
+                    const wildcard = pattern.indexOf('*');
+                    return wildcard !== -1 && !(pattern.length > 2 && pattern.endsWith('.*') && wildcard === pattern.length - 1);
+                })) {
+                errors.push(`Route "${route.id}" (${route.path}): Labels source "${sourceName}" needs exact keys or prefixes ending in .*.`);
+            }
+            continue;
+        }
+        if (rawSource.type !== 'single' && rawSource.type !== 'collection') {
+            errors.push(`Route "${route.id}" (${route.path}): source "${sourceName}" type must be labels, single, or collection.`);
+            continue;
+        }
+        if (typeof rawSource.schema !== 'string' || !rawSource.schema) {
+            errors.push(`Route "${route.id}" (${route.path}): source "${sourceName}" needs a schema.`);
+        }
+        if (rawSource.type === 'collection' && rawSource.query !== undefined && !isRecord(rawSource.query)) {
+            errors.push(`Route "${route.id}" (${route.path}): Collection source "${sourceName}" query must be an object.`);
+            continue;
+        }
+        for (const expression of pageSourceParamExpressions(rawSource.query)) {
+            const match = /^\$params\.([A-Za-z_][\w-]*)\.([A-Za-z_][\w.-]*)$/.exec(expression);
+            const param = match?.[1];
+            if (!param || !entryParamNames.has(param)) {
+                errors.push(`Route "${route.id}" (${route.path}): source "${sourceName}" references undeclared param "${param ?? expression}". Fix: use $params.<declared-entry-param>.<field>.`);
+            }
+        }
+    }
+    return errors;
+}
 function validateI18nConfig(config) {
     const rawI18n = isRecord(config.i18n) ? config.i18n : {};
     const errors = [];
@@ -192,37 +230,90 @@ function validateI18nConfig(config) {
         defaultLocale: effectiveDefaultLocale,
         locales,
         routingStrategy,
-        prefixDefaultLocale: rawRouting.prefixDefaultLocale === true,
         errors,
     };
 }
+/**
+ * Two routes that produce the same URL are only detectable once the locale
+ * segment is stripped: `/pricing` and `/:locale/pricing` both answer
+ * `/pricing`, and nothing downstream can decide which one owns it.
+ */
+function validateRouteShapeCollisions(configRoutes) {
+    const errors = [];
+    const byShape = new Map();
+    for (const route of configRoutes) {
+        const shape = route.contract.canonicalPath
+            .split('/')
+            .map((segment) => (segment.startsWith(':') ? ':param' : segment))
+            .join('/');
+        const previous = byShape.get(shape);
+        if (previous && (previous.contract.localeParam || route.contract.localeParam)) {
+            errors.push(`Routes "${previous.id}" (${previous.path}) and "${route.id}" (${route.path}) both answer "${route.contract.canonicalPath}".\nFix: keep one of them, or give them distinct paths — a locale segment does not make two routes distinct.`);
+            continue;
+        }
+        if (!previous) {
+            byShape.set(shape, route);
+        }
+    }
+    return errors;
+}
 function validateLocaleRouteCollisions(args) {
     const errors = [];
     const reservedPrefixes = new Set(args.i18n.locales.map((locale) => locale.toLowerCase()));
     for (const route of args.configRoutes) {
         const first = firstPathSegment(route.path);
         if (first && reservedPrefixes.has(first.toLowerCase())) {
-            errors.push(`Route "${route.id}" (${route.path}) uses reserved locale prefix "${first}". Keep ${args.configDisplayPath} routes canonical and unlocalized, for example "/pricing"; let fimoRoutes() or custom locale routing produce "/${first}/...".`);
+            errors.push(`Route "${route.id}" (${route.path}) uses reserved locale prefix "${first}". Declare the locale as "/:locale/..." in ${args.configDisplayPath} and as ":locale?/..." in React Router so the default locale remains unprefixed.`);
         }
     }
-    if (!args.routesSourceUsesFimoRoutes) {
+    if (!args.routesSourceUsesLegacyHelper) {
         for (const route of args.fileRoutes) {
             if (!route.path || route.isLayout) {
                 continue;
             }
             const first = firstPathSegment(route.path);
+            // `:locale` is the declared locale segment, not an accidental catch-all.
+            if (first && normalizeLocaleSpelling(first) === `:${FIMO_LOCALE_PARAM}`) {
+                continue;
+            }
             if (first?.startsWith(':') || first === '*') {
-                errors.push(`Route "${route.path}" is a top-level dynamic route in a multi-locale path-prefix project. It can capture locale URLs like "/${args.i18n.locales[0]}". Use fimoRoutes(routes) from "fimo/react-router/routes" or implement explicit custom locale routing.`);
+                errors.push(`Route "${route.path}" is a top-level dynamic route in a multi-locale project. It can capture locale URLs like "/${args.i18n.locales[0]}". Put an explicit optional ":locale?" segment first in the React Router path, or keep this route outside the localized route boundary.`);
             }
         }
     }
     return errors;
 }
-function sourceUsesFimoRoutes(fileRoutes, routesFilePath) {
-    if (fileRoutes.length === 0 || !fs.existsSync(routesFilePath)) {
+function sourceUsesLegacyFimoRoutes(routesFilePath) {
+    if (!fs.existsSync(routesFilePath)) {
         return false;
     }
-    return fs.readFileSync(routesFilePath, 'utf-8').includes('fimoRoutes(');
+    const source = fs.readFileSync(routesFilePath, 'utf-8');
+    const importMatch = source.match(/import\s*\{(?<imports>[^}]*)\}\s*from\s*['"]fimo\/react-router\/routes['"]/s);
+    const importedName = importMatch?.groups?.imports
+        ?.split(',')
+        .map((specifier) => specifier.trim().match(/^fimoRoutes(?:\s+as\s+(?<alias>[A-Za-z_$][\w$]*))?$/)?.groups?.alias ??
+        (specifier.trim() === 'fimoRoutes' ? 'fimoRoutes' : null))
+        .find((name) => Boolean(name));
+    return importedName ? new RegExp(`\\b${importedName}\\s*\\(`).test(source) : false;
+}
+/**
+ * React Router spells an omittable segment `:locale?`; the config spells the
+ * same thing `:locale`. Compare the two worlds in one spelling.
+ */
+function normalizeLocaleSpelling(routePath) {
+    return routePath.replace(`:${FIMO_LOCALE_PARAM}?`, `:${FIMO_LOCALE_PARAM}`);
+}
+/**
+ * The `src/routes.ts` paths that legitimately register one config route. A
+ * route with an optional locale answers two URL shapes, so an app may register
+ * one optional-segment route or one route per shape.
+ */
+function registrablePaths(route) {
+    const declared = normalizeLocaleSpelling(route.contract.path);
+    if (!route.contract.localeParam?.optional) {
+        return [declared];
+    }
+    return [declared, route.contract.canonicalPath];
 }
 function firstPathSegment(routePath) {
     return routePath.split('/').filter(Boolean)[0] ?? null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "bin": {
     "fimo": "dist/cli/index.js"
@@ -64,8 +64,8 @@
       "import": "./dist/runtime/react-router/index.js"
     },
     "./react-router/routes": {
-      "types": "./dist/runtime/react-router/routes.d.ts",
-      "import": "./dist/runtime/react-router/routes.js"
+      "types": "./dist/runtime/react-router/legacy/routes.d.ts",
+      "import": "./dist/runtime/react-router/legacy/routes.js"
     },
     "./react-router/preset": {
       "types": "./dist/runtime/react-router/preset.d.ts",
@@ -96,6 +96,10 @@
       "types": "./dist/runtime/paths/index.d.ts",
       "import": "./dist/runtime/paths/index.js"
     },
+    "./routes": {
+      "types": "./dist/runtime/routes/index.d.ts",
+      "import": "./dist/runtime/routes/index.js"
+    },
     "./vite": {
       "types": "./dist/build/vite/index.d.ts",
       "import": "./dist/build/vite/index.js"

package/templates/astro/.fimo/config.json

@@ -2,16 +2,24 @@
   "runtime": { "framework": "astro" },
   "i18n": {
     "defaultLocale": "en",
-    "locales": ["en"],
-    "routing": { "strategy": "path-prefix" }
+    "locales": ["en"]
   },
   "routes": {
-    "home": { "label": "Home", "path": "/" },
-    "projects": { "label": "Projects", "path": "/projects" },
+    "home": {
+      "label": "Home",
+      "path": "/:locale",
+      "params": { "locale": { "type": "locale", "optional": true } }
+    },
+    "projects": {
+      "label": "Projects",
+      "path": "/:locale/projects",
+      "params": { "locale": { "type": "locale", "optional": true } }
+    },
     "project": {
       "label": "Project",
-      "path": "/projects/:slug",
+      "path": "/:locale/projects/:slug",
       "params": {
+        "locale": { "type": "locale", "optional": true },
         "slug": { "schema": "Project", "queryField": "slug", "displayField": "title" }
       }
     }

package/templates/astro/AGENTS.md

@@ -27,7 +27,11 @@ a code-only task, or use `npx fimo@latest` for project-local code generation and
 ## Project rules
 
 - **Deploy is on-demand**, not a save step. Batch related edits into one deploy.
-- The application owns routes, locale resolution, links, HTML language/direction, and SEO. Fimo connects to those decisions.
+- With pnpm, run `pnpm install --config.dangerouslyAllowAllBuilds=true`; a bare install can skip the build scripts required by Fimo and the framework toolchain.
+- Treat the user's language request as part of setup. The first explicitly requested locale is the primary locale; put it first and set it as `i18n.defaultLocale` in `.fimo/config.json`. If no language is requested, keep `en` and state that choice. Astro reads this configuration directly, keeps the default locale unprefixed, and prefixes the others.
+- Preserve both the unprefixed default pages and the `[locale]` page tree. Astro has no optional single-segment file route, so the paired native pages keep one-locale URLs clean and allow another locale without changing the route shape. Use `Astro.currentLocale` for Fimo content reads, `getLabels`, and document language.
+- Keep `.fimo/config.json#routes` as Studio metadata aligned with Astro's page files. It does not configure Astro routing.
+- Astro owns routes, locale resolution, links, HTML language/direction, and SEO. Fimo connects to those decisions.
 - Use generated schema clients, `getLabels({ locale })`, and native components from `fimo/astro/components` for editable values.
 - Do not add React or a second deployment platform.
 - Never edit `.fimo/project.json`; it links this directory to the remote project.

package/templates/astro/astro.config.mjs

@@ -1,7 +1,14 @@
 import { defineConfig } from 'astro/config';
 import { fimo } from 'fimo/astro/config';
 
+import fimoConfig from './.fimo/config.json' with { type: 'json' };
+
 export default defineConfig({
   integrations: [fimo()],
+  i18n: {
+    defaultLocale: fimoConfig.i18n.defaultLocale,
+    locales: fimoConfig.i18n.locales,
+    routing: { prefixDefaultLocale: false },
+  },
   output: 'server',
 });

package/templates/astro/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "astro dev",
-    "build": "astro build",
+    "build": "fimo validate --json && astro build",
     "check": "astro sync && astro check"
   },
   "dependencies": {

package/templates/astro/pnpm-workspace.yaml

@@ -2,6 +2,3 @@
 # package-level allowlist because Fimo installs with dangerouslyAllowAllBuilds.
 
 packages: []
-allowBuilds:
-  esbuild: set this to true or false
-  fimo: set this to true or false

package/templates/astro/src/components/ProjectOverview.astro

@@ -6,11 +6,14 @@ import * as Project from '../schemas/Project';
 import * as SiteSettings from '../schemas/SiteSettings';
 
 interface Props {
-  locale: 'en';
+  locale: string;
+  localePrefix?: string;
   rendering: 'static' | 'server';
 }
 
-const { locale, rendering } = Astro.props;
+const { locale, localePrefix, rendering } = Astro.props;
+const prefix = localePrefix ? `/${localePrefix}` : '';
+const localize = (path: string) => `${prefix}${path}`;
 const [settings, projects, labels] = await Promise.all([
   SiteSettings.get({ locale }),
   Project.list({ locale, limit: 12 }),
@@ -19,13 +22,13 @@ const [settings, projects, labels] = await Promise.all([
 ---
 
 <main data-framework="astro" data-rendering={rendering} data-locale={locale} data-fimo-starter="projects">
-  <nav aria-label="Language">
-    <a href="/">English</a>
+  <nav aria-label="Primary">
+    <a href={localize('/')}>Home</a>
   </nav>
   <header>
     <Text as="h1" value={settings.studioName} />
     <Text as="p" value={settings.intro} />
-    <a href="/projects"><Text as="span" value={labels.t('navigation.projects')} /></a>
+    <a href={localize('/projects')}><Text as="span" value={labels.t('navigation.projects')} /></a>
   </header>
   <section>
     <Text as="h2" value={labels.t('projects.heading')} />
@@ -34,7 +37,7 @@ const [settings, projects, labels] = await Promise.all([
         <article data-project-slug={String(project.slug)}>
           <Text as="h3" value={project.title} />
           <Text as="p" value={project.summary} />
-          <a href={`/projects/${String(project.slug)}`}><Text as="span" value={project.title} /></a>
+          <a href={localize(`/projects/${String(project.slug)}`)}><Text as="span" value={project.title} /></a>
         </article>
       ))
     }

package/templates/astro/src/layouts/Base.astro

@@ -1,6 +1,6 @@
 ---
 interface Props {
-  lang: 'en';
+  lang: string;
   title: string;
 }
 

package/templates/astro/src/locales.ts

@@ -0,0 +1,4 @@
+import fimoConfig from '../.fimo/config.json';
+
+export const defaultLocale: string = fimoConfig.i18n.defaultLocale;
+export const prefixedLocales = new Set(fimoConfig.i18n.locales.filter((locale) => locale !== defaultLocale));

package/templates/astro/src/pages/[locale]/index.astro

@@ -0,0 +1,19 @@
+---
+import ProjectOverview from '../../components/ProjectOverview.astro';
+import Base from '../../layouts/Base.astro';
+import { prefixedLocales } from '../../locales';
+
+export const prerender = false;
+
+const routeLocale = Astro.params.locale;
+
+if (!routeLocale || !prefixedLocales.has(routeLocale)) {
+  return new Response(null, { status: 404, statusText: 'Not found' });
+}
+
+const locale = Astro.currentLocale ?? routeLocale;
+---
+
+<Base lang={locale} title="Fimo + Astro">
+  <ProjectOverview {locale} localePrefix={locale} rendering="server" />
+</Base>

package/templates/astro/src/pages/[locale]/projects/[slug].astro

@@ -0,0 +1,35 @@
+---
+import { getLabels } from 'fimo/astro';
+import { Text } from 'fimo/astro/components';
+
+import Base from '../../../layouts/Base.astro';
+import { prefixedLocales } from '../../../locales';
+import * as Project from '../../../schemas/Project';
+
+export const prerender = false;
+
+const routeLocale = Astro.params.locale;
+const slug = Astro.params.slug ?? '';
+
+if (!routeLocale || !prefixedLocales.has(routeLocale)) {
+  return new Response(null, { status: 404, statusText: 'Not found' });
+}
+
+const locale = Astro.currentLocale ?? routeLocale;
+
+const [project, labels] = await Promise.all([Project.getBySlug(slug, { locale }), getLabels({ locale })]);
+
+if (!project) {
+  return Astro.redirect('/404');
+}
+---
+
+<Base lang={locale} title={String(project.title)}>
+  <main data-framework="astro" data-rendering="server" data-project-slug={slug}>
+    <a href={`/${locale}/projects`}><Text as="span" value={labels.t('navigation.projects')} /></a>
+    <article>
+      <Text as="h1" value={project.title} />
+      <Text as="p" value={project.summary} />
+    </article>
+  </main>
+</Base>

package/templates/astro/src/pages/[locale]/projects/index.astro

@@ -0,0 +1,19 @@
+---
+import ProjectOverview from '../../../components/ProjectOverview.astro';
+import Base from '../../../layouts/Base.astro';
+import { prefixedLocales } from '../../../locales';
+
+export const prerender = false;
+
+const routeLocale = Astro.params.locale;
+
+if (!routeLocale || !prefixedLocales.has(routeLocale)) {
+  return new Response(null, { status: 404, statusText: 'Not found' });
+}
+
+const locale = Astro.currentLocale ?? routeLocale;
+---
+
+<Base lang={locale} title="Projects">
+  <ProjectOverview {locale} localePrefix={locale} rendering="server" />
+</Base>

package/templates/astro/src/pages/index.astro

@@ -1,10 +1,13 @@
 ---
 import ProjectOverview from '../components/ProjectOverview.astro';
 import Base from '../layouts/Base.astro';
+import { defaultLocale } from '../locales';
 
 export const prerender = true;
+
+const locale = Astro.currentLocale ?? defaultLocale;
 ---
 
-<Base lang="en" title="Fimo + Astro">
-  <ProjectOverview locale="en" rendering="static" />
+<Base lang={locale} title="Fimo + Astro">
+  <ProjectOverview {locale} rendering="static" />
 </Base>

package/templates/astro/src/pages/projects/[slug].astro

@@ -3,19 +3,21 @@ import { getLabels } from 'fimo/astro';
 import { Text } from 'fimo/astro/components';
 
 import Base from '../../layouts/Base.astro';
+import { defaultLocale } from '../../locales';
 import * as Project from '../../schemas/Project';
 
 export const prerender = false;
 
+const locale = Astro.currentLocale ?? defaultLocale;
 const slug = Astro.params.slug ?? '';
-const [project, labels] = await Promise.all([Project.getBySlug(slug, { locale: 'en' }), getLabels({ locale: 'en' })]);
+const [project, labels] = await Promise.all([Project.getBySlug(slug, { locale }), getLabels({ locale })]);
 
 if (!project) {
   return Astro.redirect('/404');
 }
 ---
 
-<Base lang="en" title={String(project.title)}>
+<Base lang={locale} title={String(project.title)}>
   <main data-framework="astro" data-rendering="server" data-project-slug={slug}>
     <a href="/projects"><Text as="span" value={labels.t('navigation.projects')} /></a>
     <article>

package/templates/astro/src/pages/projects/index.astro

@@ -1,10 +1,13 @@
 ---
 import ProjectOverview from '../../components/ProjectOverview.astro';
 import Base from '../../layouts/Base.astro';
+import { defaultLocale } from '../../locales';
 
 export const prerender = false;
+
+const locale = Astro.currentLocale ?? defaultLocale;
 ---
 
-<Base lang="en" title="Projects">
-  <ProjectOverview locale="en" rendering="server" />
+<Base lang={locale} title="Projects">
+  <ProjectOverview {locale} rendering="server" />
 </Base>

package/templates/nextjs/.fimo/config.json

@@ -7,7 +7,8 @@
   "routes": {
     "home": {
       "label": "Home",
-      "path": "/"
+      "path": "/:locale",
+      "params": { "locale": { "type": "locale", "optional": true } }
     }
   },
   "version": "4",

package/templates/nextjs/AGENTS.md

@@ -35,6 +35,11 @@ The scaffolded homepage is disposable. Replace it on the first real generation.
 ## Project rules
 
 - **Deploy is on-demand**, not a save step. Batch related edits into one deploy.
+- With pnpm, run `pnpm install --config.dangerouslyAllowAllBuilds=true`; a bare install can skip the build scripts required by Fimo and the framework toolchain.
+- Treat the user's language request as part of setup. The first explicitly requested locale is the primary locale; put it first and set it as `i18n.defaultLocale` in `.fimo/config.json`, with every requested locale in `i18n.locales`. If no language is requested, keep `en` and state that choice. That file is the only place to change: `src/locales.ts` reads it, so the served language, `<html lang>`, and the prefixed URLs follow. Never introduce a default-locale environment variable.
+- Preserve the unprefixed `app/(default)` route group and the native `app/[locale]` boundary. Each is its own root layout, so each renders `src/components/Document.tsx` with the locale that tree serves; that is what makes `<html lang>` and the Fimo locale context correct on both. Mirror new routes in both groups when they are localized. Next.js has no optional single-segment folder, so do not replace this small pattern with middleware, rewrites, or a catch-all locale router.
+- Keep the client-only `src/components/FimoPreviewBridge.tsx` inside `Document`. It reports the native Next pathname and settled locale to Studio and sends Studio navigation through Next's router; keep Next imports out of Fimo's shared runtime.
+- Keep `.fimo/config.json#routes` as Studio metadata, not as the Next.js router. In that metadata, `params.locale.optional: true` means omit the configured default locale from the URL; use `optional: false` only when every locale, including the default, must be prefixed.
 - The application owns routes, locale resolution, links, HTML language/direction, and SEO. Fimo connects to those decisions.
 - Do not add a second deployment platform.
 - Never edit `.fimo/project.json`; it links this directory to the remote project.

package/templates/nextjs/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "next dev",
-    "build": "next build",
+    "build": "fimo validate --json && next build",
     "start": "next start",
     "lint": "oxlint --deny-warnings",
     "typecheck": "next typegen && tsc --noEmit"

package/templates/nextjs/src/app/(default)/layout.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+
+import Document from '../../components/Document';
+import { defaultLocale } from '../../locales';
+
+import '../globals.css';
+
+export default function DefaultLocaleLayout({ children }: Readonly<{ children: ReactNode }>) {
+  return <Document locale={defaultLocale}>{children}</Document>;
+}