fimo 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "0.17.0",
+  "version": "0.19.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"
@@ -114,13 +118,13 @@
   },
   "scripts": {
     "build": "pnpm run clean && tsc -b tsconfig.json && chmod +x dist/cli/index.js",
-    "build:bundle": "node scripts/bundle-cli.mjs && node scripts/bundle-sveltekit.mjs",
+    "build:bundle": "node scripts/bundle-cli.mjs && node scripts/bundle-routes.mjs && node scripts/bundle-sveltekit.mjs",
     "check:types": "tsc -b tsconfig.json && tsc -p tsconfig.test.json",
     "start": "tsx src/cli/index.ts",
     "install-cli": "pnpm build && node scripts/install-cli.mjs",
     "publish-cli": "node scripts/publish-tarball.mjs",
     "publish:npm": "node scripts/publish-npm.mjs",
-    "prepublishOnly": "pnpm run build && pnpm run build:bundle",
+    "prepublishOnly": "pnpm -F @fimo/routes build && pnpm run build && pnpm run build:bundle",
     "release:bump": "node scripts/bump-version.mjs",
     "publish:dry-run": "npm publish --dry-run",
     "postinstall": "node scripts/postinstall.mjs",
@@ -152,6 +156,7 @@
     "@fimo/cli-kit": "workspace:*",
     "@fimo/framework-detect": "workspace:*",
     "@fimo/mcp": "workspace:*",
+    "@fimo/routes": "workspace:*",
     "@fimo/tsconfig": "workspace:*",
     "@modelcontextprotocol/sdk": "1.27.1",
     "@sveltejs/adapter-vercel": "6.3.4",

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/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/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>;
+}

package/templates/nextjs/src/app/[locale]/layout.tsx

@@ -0,0 +1,22 @@
+import { notFound } from 'next/navigation';
+import type { ReactNode } from 'react';
+
+import Document from '../../components/Document';
+import { prefixedLocales } from '../../locales';
+
+import '../globals.css';
+
+export default async function LocaleLayout({
+  children,
+  params,
+}: Readonly<{ children: ReactNode; params: Promise<{ locale: string }> }>) {
+  const { locale } = await params;
+
+  // The default locale is served unprefixed by `app/(default)`, so its prefix
+  // is not a second URL for the same page.
+  if (!prefixedLocales.has(locale)) {
+    notFound();
+  }
+
+  return <Document locale={locale}>{children}</Document>;
+}

package/templates/nextjs/src/app/[locale]/page.tsx

@@ -0,0 +1 @@
+export { default } from '../(default)/page';

package/templates/nextjs/src/components/Document.tsx

@@ -0,0 +1,26 @@
+import { FimoProvider } from 'fimo/next/client';
+import type { ReactNode } from 'react';
+
+import FimoPreviewBridge from './FimoPreviewBridge';
+
+/**
+ * The HTML document for one locale tree. Only a root layout may render `<html>`
+ * in the App Router, so each locale tree has its own root layout and renders
+ * this with the locale that tree serves. That is what makes `<html lang>` and
+ * the Fimo locale context correct on both the unprefixed and prefixed routes.
+ */
+export default function Document({ children, locale }: Readonly<{ children: ReactNode; locale: string }>) {
+  const previewScriptUrl = process.env.NEXT_PUBLIC_FIMO_PREVIEW_SCRIPT_URL;
+
+  return (
+    <html lang={locale}>
+      <body>
+        <FimoProvider locale={locale}>
+          <FimoPreviewBridge />
+          {children}
+        </FimoProvider>
+        {previewScriptUrl ? <script src={previewScriptUrl} defer /> : null}
+      </body>
+    </html>
+  );
+}

package/templates/nextjs/src/components/FimoPreviewBridge.tsx

@@ -0,0 +1,13 @@
+'use client';
+
+import { FimoPreviewBridge as RuntimeFimoPreviewBridge } from 'fimo/next/client';
+import { usePathname, useRouter } from 'next/navigation';
+import { useCallback } from 'react';
+
+export default function FimoPreviewBridge() {
+  const pathname = usePathname();
+  const router = useRouter();
+  const navigate = useCallback((to: string) => router.push(to), [router]);
+
+  return <RuntimeFimoPreviewBridge pathname={pathname} navigate={navigate} />;
+}

package/templates/nextjs/src/locales.ts

@@ -0,0 +1,13 @@
+import fimoConfig from '../.fimo/config.json';
+
+/**
+ * Locale policy read from the same file Fimo and Studio read, so the site
+ * language cannot drift from the project configuration. Change the locales in
+ * `.fimo/config.json#i18n`; nothing here needs editing.
+ */
+export const defaultLocale: string = fimoConfig.i18n.defaultLocale;
+
+/** Only non-default locales carry a URL prefix; the default locale stays at the site root. */
+export const prefixedLocales: ReadonlySet<string> = new Set(
+  fimoConfig.i18n.locales.filter((locale) => locale !== defaultLocale)
+);

package/templates/react-router/.fimo/config.json

@@ -11,16 +11,13 @@
   },
   "i18n": {
     "defaultLocale": "en",
-    "locales": ["en"],
-    "routing": {
-      "strategy": "path-prefix",
-      "prefixDefaultLocale": false
-    }
+    "locales": ["en"]
   },
   "routes": {
     "home": {
       "label": "Home",
-      "path": "/",
+      "path": "/:locale",
+      "params": { "locale": { "type": "locale", "optional": true } },
       "seo": {
         "title": "Home",
         "description": "Welcome"

package/templates/react-router/AGENTS.md

@@ -40,6 +40,10 @@ breaks that. Load `fimo-code` for the exact primitives, but the rule is:
 ## 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`. If no language is requested, keep `en` and state that choice.
+- Preserve the application-owned `:locale?` route boundary in `src/routes.ts` and pass its route parameter to `FimoProviders` in `LocaleLayout.tsx`. The missing parameter uses the configured default, so a one-locale site stays at `/`. Add locales in `.fimo/config.json` without rebuilding the route tree; use `:locale` without `?` only when every locale must be prefixed.
+- Keep `.fimo/config.json#routes` aligned as Studio metadata, not as the React Router source of truth. Do not add a global locale-routing strategy, a Fimo route helper, or a Fimo-owned route tree.
 - Do not add a second deploy tool (Vercel, Netlify, etc.).
 - **Never edit `.fimo/project.json`** — it links this folder to the remote project.
 - **Keep `.fimo/config.json#runtime` true to the code** — framework, `dev`/`build`/`install` commands, output directory. Update it when you rename a package script, move the build output, or change framework; the reference is `fimo skills get fimo-code --ref frameworks/hosting`.

package/templates/react-router/package.json

@@ -21,7 +21,7 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "0.17.0",
+    "fimo": "0.19.0",
     "input-otp": "^1.4.2",
     "isbot": "^5",
     "lucide-react": "^0.577.0",

package/templates/react-router/pnpm-workspace.yaml

@@ -5,6 +5,4 @@
 # (ERR_PNPM_CONFIG_CONFLICT_BUILT_DEPENDENCIES), which makes sandbox installs
 # fail before the project's `fimo` dep is available.
 
-allowBuilds:
-  esbuild: true
-  fimo: true
+packages: []

package/templates/react-router/react-router.config.ts

@@ -5,16 +5,10 @@ export default {
   appDirectory: 'src',
   ssr: false,
   presets: [fimoPreset()],
-  // Static-site generation is opt-in. By default this template builds as an
-  // SPA (single index.html shell, client-side routing). To prerender routes at
-  // build time — required for crawler-visible per-route SEO — add this line:
-  //
-  //   import { getFimoPaths } from 'fimo/paths';
-  //   prerender: async () => (await getFimoPaths()).map((p) => p.path),
-  //
-  // `getFimoPaths()` expands dynamic routes (e.g. `/blog/:slug`) by fetching
-  // schema entries from the content API. See `references/frameworks/react-router.md`
-  // in the fimo skill for the full setup pattern.
+  // Pages metadata is optional Studio editing context; it does not configure
+  // the app router or build-time paths. Existing projects that still need the
+  // legacy sitemap/simple-SSG helper can import `fimo/paths` in their own build
+  // configuration.
   buildDirectory: 'dist',
   // Feed Vite's dependency scanner the client entry + every route module.
   // Without it React Router hands Vite an EMPTY entry list, nothing is

package/templates/react-router/src/pages/LocaleLayout.tsx

@@ -0,0 +1,12 @@
+import { FimoProviders } from 'fimo/react-router';
+import { Outlet, useParams } from 'react-router';
+
+export default function LocaleLayout() {
+  const { locale } = useParams();
+
+  return (
+    <FimoProviders locale={locale}>
+      <Outlet />
+    </FimoProviders>
+  );
+}

package/templates/react-router/src/root.tsx

@@ -1,5 +1,5 @@
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { FimoProviders, FimoScripts, loadFimoMetaData, buildFimoMeta, fimoHtmlProps } from 'fimo/react-router';
+import { FimoScripts, loadFimoMetaData, buildFimoMeta, fimoHtmlProps } from 'fimo/react-router';
 import React from 'react';
 import type { MetaFunction } from 'react-router';
 import { Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
@@ -45,9 +45,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
 export default function AppRoot() {
   return (
     <QueryClientProvider client={queryClient}>
-      <FimoProviders>
-        <Outlet />
-      </FimoProviders>
+      <Outlet />
     </QueryClientProvider>
   );
 }

package/templates/react-router/src/routes.ts

@@ -1,5 +1,5 @@
-import { index } from '@react-router/dev/routes';
-import { fimoRoutes } from 'fimo/react-router/routes';
+import type { RouteConfig } from '@react-router/dev/routes';
+import { layout, route } from '@react-router/dev/routes';
 
 // Examples of React Router route patterns:
 //   index('./pages/Index.tsx'),
@@ -12,4 +12,6 @@ import { fimoRoutes } from 'fimo/react-router/routes';
 //     route('settings', './pages/dashboard/Settings.tsx'),
 //   ]),
 
-export default fimoRoutes([index('./pages/Index.tsx', { id: 'home' })]);
+export default [
+  layout('./pages/LocaleLayout.tsx', [route(':locale?', './pages/Index.tsx', { id: 'home' })]),
+] satisfies RouteConfig;

package/templates/sveltekit/.fimo/config.json

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

package/templates/sveltekit/AGENTS.md

@@ -27,6 +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.
+- 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. `src/locales.ts` derives the default and prefixed locale set from that config.
+- Preserve the native `[[locale=locale]]` route boundary. The optional parameter keeps the default locale at `/`; the matcher prevents ordinary top-level routes from being mistaken for locales. The root server layout passes the tracked `event.params` through `resolveLocale`, then sends that locale to `getLabels` and `FimoProvider`. Remove the extra brackets only when every locale must be prefixed.
+- Keep the document language request-aware: `src/hooks.server.ts` renders the initial `<html lang>`, and the root layout updates it after client navigation.
+- Keep `.fimo/config.json#routes` as Studio metadata aligned with SvelteKit's route files. It does not configure SvelteKit routing.
 - 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/sveltekit/src/app.html

@@ -1,5 +1,5 @@
 <!doctype html>
-<html lang="en">
+<html lang="%lang%">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width" />

package/templates/sveltekit/src/hooks.server.ts

@@ -0,0 +1,11 @@
+import type { Handle } from '@sveltejs/kit';
+
+import { resolveLocale } from './locales';
+
+export const handle: Handle = ({ event, resolve }) => {
+  const locale = resolveLocale(event.params);
+
+  return resolve(event, {
+    transformPageChunk: ({ html }) => html.replace('%lang%', locale),
+  });
+};

package/templates/sveltekit/src/locales.ts

@@ -0,0 +1,8 @@
+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));
+
+export function resolveLocale(params: { locale?: string }): string {
+  return params.locale ?? defaultLocale;
+}

package/templates/sveltekit/src/params/locale.ts

@@ -0,0 +1,5 @@
+import type { ParamMatcher } from '@sveltejs/kit';
+
+import { prefixedLocales } from '../locales';
+
+export const match = ((locale: string) => prefixedLocales.has(locale)) satisfies ParamMatcher;