smoodly 0.0.59 → 0.0.61

package/docs/globals/defining.md

@@ -0,0 +1,99 @@
+# Defining a global
+
+A global is content that exists once and appears on many pages: the header, the footer, the company's contact details. You declare it in code; editors edit it in one place under Globals.
+
+## Two kinds
+
+`smoodly.global()` takes a name, a title, and exactly one of `section` or `fields`:
+
+File: `smoodly/globals.ts`
+
+```ts
+import { f, smoodly } from "smoodly";
+import { headerSchema } from "@/components/sections/Header.schema";
+import { footerSchema } from "@/components/sections/Footer.schema";
+import { quoteSchema } from "@/components/sections/Quote.schema";
+
+export const header = smoodly.global({ name: "header", title: "Header", section: headerSchema, layout: true });
+
+export const footer = smoodly.global({ name: "footer", title: "Footer", section: footerSchema, layout: true });
+
+export const contact = smoodly.global({
+  name: "contact",
+  title: "Contact details",
+  fields: {
+    email: f.text(),
+    phone: f.text().optional(),
+    address: f.text().localized(),
+  },
+  layout: true,
+});
+
+export const quote = smoodly.global({ name: "quote", title: "Quote", section: quoteSchema });
+
+export const globals = [header, footer, contact, quote];
+```
+
+- A **visual global** takes a registered section's schema. Its fields, settings and styles are the section's, and it renders through the section's view. The starter's header, footer and quote are visual.
+- An **object global** takes fields of its own and renders nowhere by itself; your code reads it. The starter's contact details are one, read by the footer.
+
+Register the list in the config's `globals`. A visual global's section must be in the `sections` list too, which is why the starter's header and footer sit in `smoodly/sections.ts` although no zone lists them.
+
+## Layout globals
+
+`layout: true` says a global is part of every page: the header, the footer, the contact details the footer shows. On Astro the page's own read brings every layout global along, so the layout's `getLiveEntry` calls cost nothing; a page that hides the header simply does not read it. Leave the flag off a global that editors place in zones or that one view reads, such as the starter's quote or a form section used on a few pages: it is resolved into each page that places it, and a view that reads it pays one call. In development, a page render that reads an unflagged global prints a hint naming it, once. On Next the flag changes nothing: its data cache keeps every global until that global is published again.
+
+## In the admin
+
+*Site* in the rail lists every global with its kind, *Visual* or *Fields*, and its status in the selected language. Each opens a form like an entry's: the fields in schema order, and for a visual global the *Settings* tab's groups after them. The form autosaves, and carries the same *Publish* control, *History* and *Discard changes* as a page. A visual global's page also says on how many pages it is used.
+
+A global exists in every language from the start, so there is nothing to add or delete. Publishing is per language, as for pages. A field's value is shared across languages unless it chains `.localized()`: the starter's contact email is one value, its address is translated.
+
+## Reading a global
+
+Your code reads a global by name and language, through the [reads](../collections/queries.md). It is `null` until the global is published in that language, so the caller renders nothing rather than an empty header.
+
+**Astro**
+
+A global item is its own live collection, `globalLoader(footer)` in `src/live.config.ts`, read with `getLiveEntry("footer", { locale })`; the value is the entry's `data`:
+
+File: `src/layouts/Layout.astro`
+
+```astro
+---
+// …
+const [{ entry: header }, { entry: footer }, { entry: contact }] = await Promise.all([
+  getLiveEntry("header", { locale }),
+  getLiveEntry("footer", { locale }),
+  getLiveEntry("contact", { locale }),
+]);
+// …
+---
+// …
+    {footer && <Footer {...footer.data.fields} settings={footer.data.settings} styles={footer.data.styles} contact={contact?.data.fields} />}
+```
+
+**Next.js**
+
+`getGlobal` reads it:
+
+File: `app/[locale]/layout.tsx`
+
+```tsx
+  const [footer, contact] = await Promise.all([
+    q().getGlobal("footer", { locale }),
+    q().getGlobal("contact", { locale }),
+  ]);
+  // …
+          {footer && <FooterView {...footer.fields} settings={footer.settings} styles={footer.styles} contact={contact?.fields} />}
+```
+
+A global resolves to `{ locale, fields }`, and a visual global adds `settings` with defaults filled, and `styles`. Spread `fields` onto the section's view, with `settings` and `styles` beside it, and the section renders with the spacing steps an editor chose and the id the canvas uses to select it.
+
+## Placing a global on a page
+
+A visual global can also be placed in a zone. `z.locked(quote)` binds a zone to it, so every page of that type shows the one quote; in a freeform or sections zone that allows the global's section, the *Add section* picker offers it under *Global*. A placed global is a link, not a copy: editing it anywhere changes it everywhere, and the canvas tags it *global*.
+
+A page cannot be published in a language while a global it shows is unpublished there. Publishing the page does not publish the global; that is a click of its own, in the global's canvas card or on its page.
+
+Next, [Header and footer](../globals/header-and-footer.md) walks through the starter's layout.

package/docs/globals/header-and-footer.md

@@ -0,0 +1,117 @@
+# Header and footer
+
+The starter's header and footer are visual globals rendered by your layout, not sections placed on pages. This page walks through how they are defined, rendered and edited.
+
+## The sections
+
+The header is a section like any other, with one difference in its schema:
+
+File: `components/sections/Header.schema.ts`
+
+```ts
+export const headerSchema = smoodly.schema.section({
+  name: "header",
+  title: "Header",
+  description: "The site header: brand and navigation.",
+  fields: {
+    brand: f.text(),
+    nav: f.list(f.object({ label: f.text(), href: f.link() })).localized(),
+  },
+  sample: { brand: "Lorem Co.", nav: [{ label: "Home", href: "/" }] },
+  // Nobody pads the header from the editor: no Spacing & layout group.
+  styles: false,
+});
+```
+
+`styles: false` takes away the *Spacing & layout* group, because the header's spacing is the design's. The brand is shared across languages and the navigation is localized as a whole, so each language has its own labels and links. The footer follows the same pattern with a tagline, three link columns and a copyright line.
+
+Both are registered in `smoodly/sections.ts` and named with `smoodly.global()` in `smoodly/globals.ts`, which gives each a row under *Site* and its `sample` as starting content. No zone lists them, so the *Add section* picker never offers them. Both are `layout: true` ([Defining a global](../globals/defining.md#layout-globals)): on Astro they arrive with the page's own read, so rendering them costs no extra call.
+
+## Rendering them
+
+**Astro**
+
+The layout reads the header, the footer and the contact details as live entries, and renders the sections' views with the values spread:
+
+File: `src/layouts/Layout.astro`
+
+```astro
+---
+// …
+const [{ entry: header }, { entry: footer }, { entry: contact }] = await Promise.all([
+  getLiveEntry("header", { locale }),
+  getLiveEntry("footer", { locale }),
+  getLiveEntry("contact", { locale }),
+]);
+const codes = Object.keys(locales);
+const links = codes.length > 1
+  ? codes.map((code) => ({ code, url: href(locales[code]?.path ?? "/", code), current: code === locale }))
+  : undefined;
+---
+// …
+    {header && <Header {...header.data.fields} settings={header.data.settings} styles={header.data.styles} home={href("/", locale)} locales={links} />}
+    <main><slot /></main>
+    {footer && <Footer {...footer.data.fields} settings={footer.data.settings} styles={footer.data.styles} contact={contact?.data.fields} />}
+```
+
+The footer's view takes one prop its schema does not have, the contact object; a view is a plain `.astro` file and accepts anything. The header's language links need the page on screen, and in Astro the layout knows it: every page view passes its own `locales` map to the layout, which Astro renders after the page.
+
+**Next.js**
+
+The root layout reads the footer and the contact details and renders the footer's view:
+
+File: `app/[locale]/layout.tsx`
+
+```tsx
+import { FooterView } from "@/components/sections/Footer";
+import { q } from "@/smoodly/server";
+// …
+  const [footer, contact] = await Promise.all([
+    q().getGlobal("footer", { locale }),
+    q().getGlobal("contact", { locale }),
+  ]);
+  return (
+    <html lang={locale} className={`${serif.variable} ${sans.variable}`}>
+      <body>
+        <NextIntlClientProvider>
+          {children}
+          {footer && <FooterView {...footer.fields} settings={footer.settings} styles={footer.styles} contact={contact?.fields} />}
+        </NextIntlClientProvider>
+      </body>
+    </html>
+  );
+```
+
+The layout renders `FooterView`, the view, rather than `Footer`, the paired component, because it passes one prop the footer's schema does not have: the contact object. A paired component accepts only its schema's fields; a view is a plain component and accepts anything. The footer exports both.
+
+The header is not in the layout. A layout cannot know which page is on screen, and the language links in the header must land on the same page in the other language. So every page type renders the header itself, through the starter's `PageFrame`, from the page's own language map:
+
+File: `components/PageFrame.tsx`
+
+```tsx
+export async function PageFrame({ locale, locales, children }: {
+  locale: string;
+  locales: Record<string, LocaleAlternate | null>;
+  children: ReactNode;
+}) {
+  const header = await q().getGlobal("header", { locale });
+  const codes = Object.keys(locales);
+  const links: LocaleLink[] | undefined = codes.length > 1
+    ? codes.map((code) => ({ code, url: href(locales[code]?.path ?? "/", code), current: code === locale }))
+    : undefined;
+  return (
+    <>
+      {header && <HeaderView {...header.fields} settings={header.settings} styles={header.styles} home={href("/", locale)} locales={links} />}
+      <main>{children}</main>
+    </>
+  );
+}
+```
+
+On a single-language site there are no links and the header shows the brand and navigation alone. [Language switcher and hreflang](../languages/language-switcher.md) covers the `locales` map.
+
+## Editing them
+
+Editors change the header and footer under *Site*, or in any page's canvas: both are selectable there, tagged *global*, with their own form and their own *Publish* in the inspector. The header's navigation edits in place like any list with [marks](../content-modeling/marks.md). Publishing a page never publishes the footer, because a footer going live on every page is a deliberate click.
+
+Next, [The media library](../media/library.md).

package/docs/index.md

@@ -0,0 +1,83 @@
+# Smoodly
+
+> Smoodly is a code-first CMS for Astro and Next.js. A developer registers sections, collections and page types in code, editors build pages in a visual admin mounted in the site at /admin, and the content lives in Smoodly Cloud, read by the site over the API.
+
+Start a site with the installer. It creates a fresh app; it does not add Smoodly to an existing one. With these flags it asks nothing:
+
+    npx create-smoodly-app <folder> --yes --framework astro|next --starter blank|lorem [--locales en,fi] --space <sp_…> --secret-key <sk_…> --publishable-key <pk_…>
+
+The three space values are on the project's production space page at smoodly.io. In an installed site, the guides for that version are in node_modules/smoodly/docs/ and the project's AGENTS.md holds the working rules.
+
+## Getting started
+
+- [Install with create-smoodly-app](getting-started/install.md): One command creates a website with the Smoodly admin mounted, connected to a space that holds its content. At the end you have the Lorem Co. starter running on your machine.
+- [Project structure](getting-started/project-structure.md): What create-smoodly-app puts in your project, and which files you change as you build the site. Everything is ordinary code in your repository; Smoodly adds a folder of setup and mounts the admin.
+- [Your first page](getting-started/first-page.md): Create a page in the admin, fill it with sections and publish it, as an editor would. Then look at the code that decided what the editor was allowed to do.
+- [Content from code](getting-started/content-from-code.md): Write pages, entries, globals and images from a script instead of the admin: to seed a new site, or to move a client's old content in. At the end you have a script you can run again after it stops halfway.
+- [Working together](getting-started/working-together.md): Who can open the admin, and what happens when two people open the same page: the admin shows who is where, and never lets one person's save silently overwrite another's.
+- [Keys](getting-started/keys.md): The space id and the two keys a Smoodly site uses, where each one may live, what the public one can reach, and how to rotate or revoke a key.
+- [Deploying](getting-started/deploying.md): Put your Smoodly site on the internet: give it the production space's values and let its build push the schema; then, once it is live, add a preview space to develop against.
+- [Export and import](getting-started/export-and-import.md): Copy a space's content into a folder, and from the folder into a new space: every page, entry, version and media file. It is how you move a site or keep a copy.
+
+## Content modeling
+
+- [Modeling content](content-modeling/overview.md): The five things you register, what each one holds, and where it lives in your project. Read this once; the rest of the group takes them one at a time.
+- [Defining a section](content-modeling/sections.md): A section is a full-width component editors place in a zone. You describe its fields once, in a schema file, and Smoodly derives the editor form, the Add section entry and the TypeScript props from that one definition. This page walks through the Lorem Co. starter's Hero.
+- [Defining a page type](content-modeling/page-types.md): A page type is a page component with zones: the places where editors add sections. This page walks through the Lorem Co. starter's Home and Page types, and what a page type learns about its place in the site.
+- [Zones and freedom](content-modeling/zones.md): A zone is a place in a page type where editors add sections. Its policy sets how much they may change there, from filling one section's fields to placing any section in any order.
+- [Settings, styles and CSS](content-modeling/styles-and-settings.md): Beyond its fields, a placed section carries three more things editors can change: the settings you declare, Smoodly's own spacing and width steps, and a custom CSS box you can turn on. All three sit on the Settings tab.
+- [The custom section](content-modeling/custom-section.md): The one section editors lay out themselves: rows of richtext columns on a 12-column grid, offered where a zone allows it. You turn it on, pick what its columns may hold, and style the result; Smoodly owns the grid.
+- [Marks and inline editing](content-modeling/marks.md): Marks are the attributes a section spreads on the elements that render its fields. They tell the canvas which field an editor clicked, so text edits in place and everything else opens in the inspector.
+- [When the schema changes](content-modeling/changing-schemas.md): Sites change after launch: a section goes, a field is renamed, a zone gets stricter. This page covers what stored content keeps when the code moves on, how the admin shows it, and what Publish refuses until an editor fixes it.
+
+## Fields
+
+- [All fields](fields/overview.md): Every field builder on f, what editors see for each, and the chain of modifiers they share. The pages that follow take them a few at a time.
+- [Text, number, date and time](fields/text.md): The plain values: a line of text, a number, a date, a date with a time, and the slug that becomes part of an entry's URL.
+- [Richtext and elements](fields/richtext.md): Formatted text stored as structured data, the toolset that decides what editors may put in it, and the elements they can insert between the paragraphs.
+- [Link](fields/link.md): A link is a text box that takes a full URL or a path on your site. Pair it with a label in an object to make a button.
+- [Choices](fields/choices.md): A switch, a dropdown, a row of pills or a checkbox list: the fields that pick from a closed set you declare.
+- [Image, video and file](fields/media.md): The three media fields, the resolved values your view receives, and the components that render them.
+- [List and object](fields/list-and-object.md): Group fields into one value with an object, or let editors repeat a value with a list. The two nest one level, which is as far as a sidebar form stays readable.
+- [Reference and tags](fields/reference-and-tags.md): A reference points at an entry in a collection and arrives in the view already loaded. Tags are short labels editors reuse across entries.
+- [Conditional fields](fields/conditional.md): Hide a field while another field has a certain value, so editors see only the fields that apply.
+
+## Pages
+
+- [The page tree](pages/page-tree.md): How editors create, arrange and remove pages in the admin, and what your configuration allows them to do.
+- [Paths and slugs](pages/paths-and-slugs.md): A page's URL is derived from its place in the page tree: each item contributes one slug. This page covers what a slug may be, which URLs your code reserves, how a URL changes and how old addresses redirect.
+- [Drafts and publishing](pages/drafts-and-publishing.md): Every change saves as a draft on its own. Publish makes the draft live, after Smoodly checks it. This page covers the three states, what publish checks, and the two ways back.
+- [Version history](pages/version-history.md): Every publish keeps a version. Editors look back at any of them and restore one as the new draft, without touching what is live.
+- [SEO and social](pages/seo.md): A page type can give its pages an SEO & Social tab: a title, a description, a social image and a switch to hide the page from search engines. Smoodly turns them into the page's metadata.
+
+## Collections
+
+- [Defining a collection](collections/defining.md): A collection is a content type with a fixed shape and many entries: posts, people, products. You declare its fields once; editors get a list, a form and publishing for it.
+- [Entry pages](collections/entry-pages.md): Give a collection a path and each entry gets its own URL. The entry page is the component that renders one entry there.
+- [Queries](collections/queries.md): Read entries, globals and the page tree from your own views, typed by your registry, cached, and aware of drafts.
+- [Ordering](collections/ordering.md): A collection has one order, set in its schema, that the admin's list and your queries share.
+
+## Globals
+
+- [Defining a global](globals/defining.md): A global is content that exists once and appears on many pages: the header, the footer, the company's contact details. You declare it in code; editors edit it in one place under Globals.
+- [Header and footer](globals/header-and-footer.md): The starter's header and footer are visual globals rendered by your layout, not sections placed on pages. This page walks through how they are defined, rendered and edited.
+
+## Media
+
+- [The media library](media/library.md): Every image, video and file editors upload lives in one library. A field stores a reference to an asset, so one photo can appear in many places and be found from each of them.
+- [Images and crops](media/images-and-crops.md): An image field stores which asset to show and how to frame it. Smoodly's media host cuts the framed area at the width the layout needs, in a modern format, and the image component renders it without layout shift.
+
+## Languages
+
+- [Locales and routing](languages/locales.md): A site publishes in one language or several. This page covers declaring the languages, how each gets its own URLs, and what editors see when a page exists in some languages and not others.
+- [Localized fields](languages/localized-fields.md): On an entry or a global, a field is shared across languages unless it chains .localized(). This page covers the rule, where it applies and what it means for queries.
+- [Language switcher and hreflang](languages/language-switcher.md): Every page and entry knows its own address in every language. A language switcher links from that map, and the site's hreflang tags come from the same one.
+
+## Frameworks
+
+- [Astro](frameworks/astro.md): How Smoodly plugs into an Astro project: one integration in astro.config, views by file name, reads as live collections, pages cached whole and expired by tag, and what happens on a request. The installer writes all of it; this page is for reading it.
+- [Next.js](frameworks/nextjs.md): How Smoodly plugs into a Next.js app: the one route file, the server seam, the admin route group, and what happens on a request. The installer writes all of it; this page is for reading it.
+
+## Reference
+
+- [Upgrading](reference/upgrading.md): Update the package and deploy. Your content model lives in your code and every build pushes it to your space: there is no migration to run.

package/docs/languages/language-switcher.md

@@ -0,0 +1,103 @@
+# Language switcher and hreflang
+
+Every page and entry knows its own address in every language. A language switcher links from that map, and the site's hreflang tags come from the same one.
+
+## The language map
+
+A page type's view gets `page.locales`, and an entry page gets `locales`: one key per supported language. The value is the page's `slug`, `path` and `url` in that language, or `null` where the page does not exist or is not published there. In the editor's canvas an unpublished translation still counts; on the public site it never links.
+
+A switcher links to the same page where it exists, and to that language's home otherwise. The blank starter does it in one component:
+
+**Astro**
+
+File: `src/components/LocaleNav.astro`
+
+```astro
+---
+import { href } from "smoodly/astro/runtime";
+// …
+const codes = Object.keys(locales);
+---
+{codes.length > 1 && (
+  <nav class="container locales" aria-label="Language">
+    {codes.map((code) => <a href={href(locales[code]?.path ?? "/", code)} aria-current={code === locale ? "page" : undefined}>{code}</a>)}
+  </nav>
+)}
+```
+
+`href` from `smoodly/astro/runtime` adds the language prefix the site uses. With one language the map has one key and the component renders nothing, which is why the single-language scaffold shares the file.
+
+**Next.js**
+
+File: `components/LocaleNav.tsx`
+
+```tsx
+export function LocaleNav({ locale, locales }: { locale: string; locales: Record<string, LocaleAlternate | null> }) {
+  const codes = Object.keys(locales);
+  if (codes.length < 2) return null;
+  return (
+    <nav className="container locales" aria-label="Language">
+      {codes.map((code) => (
+        <a key={code} href={href(locales[code]?.path ?? "/", code)} aria-current={code === locale ? "page" : undefined}>{code}</a>
+      ))}
+    </nav>
+  );
+}
+```
+
+`href` from `smoodly/server.ts` adds the language prefix the site uses. With one language the map has one key and the component renders nothing, which is why the single-language scaffold shares the file.
+
+## Why the page decides it
+
+The links must land on the same page in the other language, so they come from the page on screen.
+
+**Astro**
+
+Every page view passes its own `locales` map to the layout, and the layout renders the header with the links. Astro renders the page before its layout, so the layout knows which page is on screen. [Header and footer](../globals/header-and-footer.md) has the file.
+
+**Next.js**
+
+The switcher lives with the page, not in the layout, because a layout cannot know which page is on screen and the links must land on the same page in the other language. The Lorem Co. starter renders its header, links included, from every page type through `PageFrame`:
+
+File: `components/PageFrame.tsx`
+
+```tsx
+  const header = await q().getGlobal("header", { locale });
+  const codes = Object.keys(locales);
+  const links: LocaleLink[] | undefined = codes.length > 1
+    ? codes.map((code) => ({ code, url: href(locales[code]?.path ?? "/", code), current: code === locale }))
+    : undefined;
+```
+
+[Header and footer](../globals/header-and-footer.md) has the whole file.
+
+## hreflang
+
+**Astro**
+
+`Head` from `smoodly/astro/components` writes one hreflang link per language where the page is published, from the same map the switcher reads. A single-language site gets none, only the page's canonical link. The links are absolute on `site` in `astro.config.ts`, which the starter reads from `SITE_URL`: set it to the site's real address, as [SEO](../pages/seo.md) explains.
+
+File: `src/layouts/Layout.astro`
+
+```astro
+    <Head of={head} fallback="Lorem Co." />
+```
+
+The visitor picks a language through the switcher; nothing redirects by browser language.
+
+**Next.js**
+
+`smoodlyMetadata` in the route files emits `alternates.languages` for every page and entry, from the same map the switcher reads: only the languages where the page has a URL, each through `href`. A single-language site emits none, only the page's canonical link. The links are absolute on the host in `SITE_URL`, which the installer sets to `http://localhost:3000`: set it to the site's real address, as [SEO](../pages/seo.md) explains.
+
+next-intl could derive hreflang and redirect visitors by browser language on its own, and the scaffold turns both off:
+
+File: `i18n/routing.ts`
+
+```ts
+  alternateLinks: false,
+  localeDetection: false,
+```
+
+Both assume a page has the same slug in every language. Once slugs translate, a derived hreflang points at a URL that does not exist, and a detection redirect keeps the English segments under `/fi/` and lands on a 404. So the visitor picks a language through the switcher, and the tags come from the content.
+
+Next, [Frameworks](../frameworks/astro.md).

package/docs/languages/locales.md

@@ -0,0 +1,119 @@
+# Locales and routing
+
+A site publishes in one language or several. This page covers declaring the languages, how each gets its own URLs, and what editors see when a page exists in some languages and not others.
+
+## Declaring the languages
+
+The config names the default language and the supported set. A single-language site declares one:
+
+File: `smoodly/config.ts`
+
+```ts
+  locales: { default: "en", supported: ["en"] },
+```
+
+**Astro**
+
+A multilingual site, which the installer scaffolds when you answer yes to *multilingual*, names the set twice: in `i18n` in `astro.config.ts`, for Astro's routing, and in the config. The installer writes both, and the site refuses to start when they disagree:
+
+File: `astro.config.ts`
+
+```ts
+  i18n: { locales: ["en", "fi"], defaultLocale: "en" },
+```
+
+File: `src/smoodly/config.ts`
+
+```ts
+  locales: { default: "en", supported: ["en", "fi"] },
+```
+
+**Next.js**
+
+A multilingual site, which the installer scaffolds when you answer yes to *multilingual*, keeps the set in one place for [next-intl](https://next-intl.dev) and imports it into the config:
+
+File: `i18n/routing.ts`
+
+```ts
+export const routing = defineRouting({
+  locales: ["en", "fi"],
+  defaultLocale: "en",
+  localePrefix: "as-needed",
+  alternateLinks: false,
+  localeDetection: false,
+});
+```
+
+File: `smoodly/config.ts`
+
+```ts
+  locales: { default: routing.defaultLocale, supported: [...routing.locales] },
+```
+
+The config cannot go the other way round: the proxy that routes languages runs in the edge runtime and cannot load the registry.
+
+A locale code is a plain string such as `en`, `fi`, `en-US` or `zh-Hant`. Adding a language later is a config change; every fixed page and global gets a row in it on the next admin load.
+
+## One URL per language
+
+Every page and entry has its own slug in each language it exists in, so URLs translate whole: `/company/about-us` in English can be `/fi/yritys/tietoa` in Finnish. Fixed pages and collection paths take a per-language map in code; the starter's Articles index is `posts` in English and `artikkelit` in Finnish.
+
+**Astro**
+
+The language prefix is Astro's: the default language has none, unless `routing: { prefixDefaultLocale: true }` in `i18n` says so, and the others get theirs. Smoodly follows the same rule. `href` from `smoodly/astro/runtime` turns a language-relative path into a site URL, and everything that hands out a URL goes through it:
+
+File: `src/layouts/Layout.astro`
+
+```astro
+---
+// …
+  ? codes.map((code) => ({ code, url: href(locales[code]?.path ?? "/", code), current: code === locale }))
+// …
+---
+```
+
+On a single-language site it returns the path unchanged. The admin sits outside the language prefix. A site that prefixes the default language says so in the config too, with `routing: { prefixDefaultLocale: true }`, so the links Smoodly builds for editors carry the prefix; the site refuses to start when the two disagree.
+
+**Next.js**
+
+The language prefix is next-intl's: with `as-needed`, the default language has none and the others get theirs. Smoodly never adds a prefix itself. One function in `smoodly/server.ts` turns a language-relative path into a site URL, and everything that hands out a URL goes through it:
+
+File: `smoodly/server.ts`
+
+```ts
+export const href = (path: string, locale: string) => getPathname({ locale, href: path });
+```
+
+On a single-language site the same function returns the path unchanged. The proxy skips `/admin`, which sits outside the language segment and has no prefix. A site whose `localePrefix` is `always` says so in the config too, with `routing: { prefixDefaultLocale: true }`, so the links Smoodly builds for editors carry the prefix.
+
+## Pages that exist in some languages
+
+A page or an entry exists in the languages it has been added to, and nothing falls back: a page that exists only in Finnish is a 404 in English. The pages list and every collection list have a language picker, and a page missing from the selected language shows dimmed, with *Add en* in its menu.
+
+Adding a language copies the content on screen as the first draft in the new language, for the editor to translate. A page can be added to a language only when its parent exists there, and removed from one only while no child page has it. Fixed pages, collection mounts and globals exist in every language from the start and never lose one.
+
+Publishing is per language. A page published in English and edited in Finnish is *Published* in one and *Unpublished changes* in the other, and each language has its own history.
+
+## One order, or one per language
+
+Editors drag pages into an order in the page tree, and entries in a collection ordered `"manual"`. By default that order is shared: a drag made in any language reorders every language.
+
+Add `order: "perLocale"` to `locales` in the config, next to `default` and `supported`, and each language keeps its own. A drag then reorders only the language selected in the list, and the page tree, a page's `children` and a manual collection's queries return the order of the language they are read in. Until an editor drags, every language has the order it had before.
+
+Only the order differs. A page still sits under the same parent in every language; moved under a new parent, it lands where it was dropped in the selected language and last in the others. A page added to a language starts where the language it was copied from has it.
+
+Setting `order` back to `"shared"` (or removing it) keeps each language's order as it is until the next drag among the same siblings, which every language then takes.
+
+## The site's own words
+
+Labels that are not content, such as *All articles* or *min read*, are yours to translate.
+
+**Astro**
+
+The starter keeps them in `src/messages/<locale>.json` and reads them through `src/strings.ts`, with no library behind it. A language without its own file shows the English words.
+
+**Next.js**
+
+The multilingual starter keeps them in `messages/<locale>.json` and reads them through next-intl; the single-language starter ships the English map with no library behind it.
+
+Next, [Localized fields](../languages/localized-fields.md).

package/docs/languages/localized-fields.md

@@ -0,0 +1,61 @@
+# Localized fields
+
+On an entry or a global, a field is shared across languages unless it chains .localized(). This page covers the rule, where it applies and what it means for queries.
+
+## The rule
+
+`.localized()` gives a field its own value per language. Without it, one value serves every language:
+
+File: `smoodly/collections.ts`
+
+```ts
+export const people = smoodly.collection({
+  name: "people",
+  title: "People",
+  titleField: "name",
+  order: "manual",
+  fields: {
+    name: f.text(),
+    role: f.text().localized(),
+  },
+});
+```
+
+A person's name is the same in Finnish and English; the role is translated. Shared is the default because most of an entry is: the photo, the date, the author, the price. The starter's articles localize the title, the excerpt, the body and the tags, and share the image, the date and the author.
+
+A global follows the same rule. The contact details share the email and localize the address; the header shares the brand and localizes the navigation.
+
+## Where it applies
+
+| Place | Effect of .localized() |
+| --- | --- |
+| `Collection and global fields` | Decides storage: the field gets a value per language. |
+| `slug` | Always per language, with or without .localized(): each language has its own URL. |
+| `Lists and objects` | Localizes the whole value. Inside an item or a subfield it is a type error; localize the top-level field that holds it, for a list of objects the list. |
+| `Settings` | Never. A layout choice is the same in every language, and .localized() on a setting throws. |
+| `Page fields` | Not needed: page fields are stored per language already. |
+| `Section fields on a page` | No effect on storage. A page's content is per language as a whole. |
+
+A page's whole tree is per language: adding a language copies the tree, and from then on the two are edited apart. That is why a page's sections need no `.localized()`, and why a change made in English is not mirrored in Finnish.
+
+## In the form
+
+On a multilingual site the entry and Globals forms mark every shared field with a globe-off icon, so an editor translating knows which values will change in every language at once. Adding a language copies every field as the first draft, shared and localized alike; the shared ones then stay in step by themselves.
+
+## Changing it later
+
+Adding or removing `.localized()` on a field that already holds content moves nothing in storage:
+
+- **Turning it on**: the value saved while the field was shared stays as every language's fallback. Each language shows it until an editor saves that language, which gives the language its own value. Until then, the form's notice says the value is still shared.
+- **Turning it off**: each language keeps showing its own value until it is saved. The first save in a language makes that language's value the one every language shows, and the form warns about it before the save.
+
+[When the schema changes](../content-modeling/changing-schemas.md) covers the other changes and the *Content health* page that lists them.
+
+## In code
+
+Reads merge the shared and the localized values for the language asked, so a view sees one flat set of fields. Two things follow from the split:
+
+- A `where` filter in a [query](../collections/queries.md) matches shared fields only. Filtering on a localized field or on the slug is refused, because those live per language.
+- A collection's `order.by` must be a shared field, because the order is one list for every language.
+
+Next, [Language switcher and hreflang](../languages/language-switcher.md).