Multilingual Content
Astronaut CMS reads the languages your site already declares in astro.config.ts and edits localized collections language by language.
There is nothing to configure.
Declare your languages the way Astro’s internationalization guide describes:
export default defineConfig({ i18n: { defaultLocale: "en", locales: ["en", "de"], }, integrations: [mdx(), react(), cms()],});Then organize each localized collection into one directory per language, as Astro’s i18n recipe recommends:
src/content/posts/├── en/│ ├── hello-world.mdx│ └── release-notes.mdx└── de/ └── hello-world.mdxEntry ids become en/hello-world and de/hello-world.
The part after the language is the same across translations, and that is how the CMS pairs them up.
In the admin panel
Section titled “In the admin panel”A collection organized this way is edited one language at a time:
- Language tabs replace the locale directories in the collection listing, and switching keeps the folder you were browsing (
en/guideslands onde/guides). - Translation badges on every entry show which languages it exists in. A dashed, faded badge means that translation is missing — useful when your site silently falls back to the default language, where a missing translation is otherwise invisible.
- A language switcher in the entry editor jumps between an entry’s translations. Languages it does not have yet appear with a
+: choosing one creates the translation as a copy of the entry on screen, so you translate real text and keep its frontmatter, components and media instead of starting from an empty form. - New entries get a language dropdown, so the CMS writes the file into the right directory for you.
- The AI assistant is told your languages and the id convention, so you can ask it to translate an entry and it will write the counterpart under the target language.
Which collections are localized
Section titled “Which collections are localized”The CMS decides per collection, from the entries themselves: a collection is localized when every one of its entries sits inside a language directory.
So a localized posts collection and a language-neutral publications collection can live side by side without any per-collection configuration.
A single entry outside a language directory switches the collection back to the plain folder view, so no entry is ever hidden behind a language tab. An empty collection counts as localized, which lets you create its first entry straight into a language.
Localized singletons
Section titled “Localized singletons”A singleton can hold one file per language, such as the texts of a site’s header and footer. Its pattern is a language folder followed by one literal file:
const texts = defineCollection({ loader: glob({ pattern: "*/site.yml", base: "src/content/texts" }), schema: z.object({ tagline: z.string(), openingHours: z.string() }),});The admin opens the default language’s entry from the navigation, and the language switcher of the entry moves between the others, with a + creating a missing one as a copy.
Nothing else creates, renames or deletes an entry.
The default language’s file is required, and the build fails without it, while a translation may be missing or deleted, since the site falls back to the default language.
Localized fields
Section titled “Localized fields”A language-neutral entry often holds a few values that differ per language, such as a translated title next to an address and a logo.
Declare them with localized(), which takes the schema of one language’s value:
import { localized } from "astronaut-cms/config";
const company = defineCollection({ loader: glob({ pattern: "company.yml", base: "src/content" }), schema: ({ image }) => z.object({ name: z.string(), logo: image(), slogan: localized(z.string()), hours: localized(z.object({ days: z.string(), time: z.string() })), }),});slogan: de: Wein und Wohnen an der Mosel en: Wine and holidays on the MoselleThe admin edits the field with a tab per language, a missing translation dashed.
The default language is required: saving refuses an entry without it, and the build fails on one.
In a component’s props, take localized from the helpers its props function is handed.
Reading localized content
Section titled “Reading localized content”astronaut-cms/content reads localized content the way the admin edits it, falling back to the default language:
---import { getCollection, getEntry } from "astro:content";import { getLocalizedEntry, localizeEntries, pickLocale } from "astronaut-cms/content";
const lang = Astro.currentLocale ?? "en";// Every post once, in this language where it is translated, flagged `isFallback` where not.const posts = localizeEntries(await getCollection("posts"), lang);// One entry, such as a localized singleton's, by the id without its language.const texts = await getLocalizedEntry("texts", "site", lang);// One value of a localized field.const company = await getEntry("company", "company");const slogan = pickLocale(company.data.slogan, lang);---Each localized entry comes with its slug, the id without the language, which is the path a site usually routes it under.
Overriding the languages
Section titled “Overriding the languages”Pass i18n to cms() to use a different set of languages than the site routes with, or false to turn the feature off and treat language directories as ordinary folders:
cms({ i18n: { locales: ["en", "de", "fr"], defaultLocale: "en" },});