Add content internationalization

[timmy-why]

Hey! 👋 This PR adds content internationalization to Keystatic — here's the gist.

Adds content i18n so you can author a collection or singleton in multiple languages.

Set i18n on the config, mark an entry localized, and drop a {locale} token into its path:

export default config({
  i18n: {
    locales: { en: 'English', pl: 'Polski', de: 'Deutsch' },
    defaultLocale: 'en',
  },
  collections: {
    posts: collection({
      label: 'Posts',
      localized: true,
      path: 'content/posts/{locale}/*',
      slugField: 'title',
      schema: { /* … */ },
    }),
  },
});

Each language gets its own file/folder on disk (content/posts/en/…, content/posts/pl/…), but the entry still shows up once in the navigation — a language switcher at the top of the sidebar decides which one you're editing. Entries without a {locale} token stay shared across all languages. Note this localizes your content, which is separate from the existing locale option that just sets the Admin UI language.

Since the token is just a folder in the path prefix, you can turn this on for an existing multi-language project without moving any files.

The Reader API reads one language at a time — createReader/createGitHubReader now take a { locale } option:

const reader = createReader(process.cwd(), config, { locale: 'en' });

Config is validated up front, so a localized entry without a {locale} token (or vice versa), a missing i18n, or a bad defaultLocale all fail with a clear error instead of breaking later.

Scoped to @keystatic/core. Docs are in the new Internationalization page, and there are tests for the path/token handling and locale-scoped reads.

Demo

Here's the flow end to end — opening a singleton and a collection while switching languages: for a singleton the form fields below swap to the selected locale's values automatically, and for a collection the list filters down to that language's entries:

i18n.showcase.mov

And the same language switcher above the navigation with GitHub mode, so you can see it isn't tied to local mode:

[changeset-bot]

🦋 Changeset detected

Latest commit: cd7e012

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@keystatic/core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[eremannisto]

This would be amazing! ⬆️

[maxmorozoff]

Nice work so far. Could you also extend this to support Astro's prefixDefaultLocale: false behavior?

[timmy-why]

Nice work so far. Could you also extend this to support Astro's prefixDefaultLocale: false behavior?

Thanks! Before I look into it — could you share what you're after with this? Just want to understand the use case.

The reason I ask: Astro's prefixDefaultLocale is about page URLs, not content folders. Keystatic content already works fine with a prefixDefaultLocale: false site whether you keep language folders (en/, pl/ — just examples here) or not, so this wouldn't unlock anything new — it'd only change how files sit on disk (default language without an en/ folder, translations in subfolders).

The main case I can think of is an existing repo whose default content already sits at the collection root, where you'd want to add translations without moving those files into en/ first. Worth noting that migrating is a one-time move, and Git preserves history through it:

mkdir -p content/posts/en
git mv content/posts/*.mdoc content/posts/en/

Then switch the collection path from content/posts/* to content/posts/{locale}/* and add your other locales alongside.

There's also a catch with collections that use the ** path wildcard (it lets a collection store entries across nested subfolders, with slugs like en/post-1). Say a collection is set up as content/posts/**, with a folder per language:

content/posts/en/post-1.mdoc
content/posts/pl/post-1.mdoc
content/posts/de/post-1.mdoc

Removing the folder for the default language would put the English entries directly under content/posts/, while pl/ and de/ stay as subfolders. Since ** scans every subfolder, listing the English entries would also sweep in the pl/ and de/ ones. So it'd need some extra handling to keep the languages separate.

Is it the existing-repo case, or something else you're running into?

[maxmorozoff]

@timmy-why thanks for the detailed breakdown!

The main driver here isn't just migrating existing repos, but supporting a standard Astro pattern.

For Astro sites configured with prefixDefaultLocale: false - whether in src/pages (which can also be defined using .md files) or Astro's content collections under src/content/**/*.{md,mdx,mdoc,json,...} - as well as Starlight docs sites using a root locale, the default language files live at the root, while translations go into subdirectories. You can see this pattern in action in Starlight's own repo.

Supporting this structure:

content/posts/post-1.mdoc
content/posts/pl/post-1.mdoc
content/posts/de/post-1.mdoc

...is crucial for native Astro/Starlight compatibility, even though I understand the ** wildcard makes this tricky. Do you think there's a way to work around that?

[timmy-why]

@maxmorozoff you were right — Starlight deriving the locale from the directory, and Markdown in src/pages being routed by file path, make the on-disk layout load-bearing. Implemented in this PR.

What's in

i18n.prefixDefaultLocale: false removes the {locale} segment for the default language while the others keep theirs — the structure you posted:

content/posts/post-1.mdoc      # default
content/posts/pl/post-1.mdoc

Defaults to true, so it's opt-in. Works for collections and singletons.

The ** problem is handled the way Starlight handles it: the config declares the locale set, so when listing the default language Keystatic skips the directories named after the other locales. Only ** needs it — * slugs can't contain /. The tradeoff is documented: locale codes become reserved at the root of a ** collection, and the Admin UI rejects such a slug instead of silently overwriting the other language's entry.

Trying it

Preview packages are published per commit:

{
  "dependencies": {
    "@keystatic/core": "https://pkg.pr.new/timmy-why/keystatic/@keystatic/core@cd7e012c",
    "@keystatic/astro": "https://pkg.pr.new/timmy-why/keystatic/@keystatic/astro@cd7e012c"
  },
  "overrides": {
    "@keystatic/core": "$@keystatic/core"
  }
}

overrides makes @keystatic/astro dedupe onto the same core (otherwise you get two copies of React). Then npm install.

Keystatic config for a Starlight root locale (Starlight on defaultLocale: 'root'):

i18n: {
  locales: { en: 'English', fr: 'Français' },
  defaultLocale: 'en',
  prefixDefaultLocale: false,
},
collections: {
  docs: collection({
    label: 'Docs',
    localized: true,
    path: 'src/content/docs/{locale}/**',
    // …
  }),
},

English resolves to src/content/docs/**, French to src/content/docs/fr/**.

I verified it on two throwaway Astro 7 projects — a Starlight site with a root locale and a plain blog covering both your cases (** collection + Markdown in src/pages). Reader, Admin UI, dev and production build all behave:

EN slugs: ["guides/example","index","reference/example"]
FR slugs: ["guides/example","index"]
EN read("fr/index") -> null