Skip to main content
A translation is a second file next to a post, with the language in its name. It keeps the post’s slug, so blog/launch.mdx and its German translation blog/launch.de.mdx are published at /blog/launch and /blog/de/launch.
If your whole site is in one language other than English, you don’t need translations. Set language instead.

Translate your first post

1

List your languages

Add the languages you translate into to blog.json. language is the language of your original posts and defaults to English, so you only need it when your originals aren’t in English:
blog.json
Use language tags like de, fr, ja or pt-BR, up to 20.
2

Copy a post and add the language to its name

Copy the original next to itself and put the language before the extension:
You can also create the file in the site’s Editor in Notra.
3

Translate the title and the text

Translate title, description and the body. The date, authors and tags can stay as copied, or you can delete them, because every language shares the original’s:
blog/launch.de.mdx
4

Preview and publish

Run notra dev and open http://localhost:4321/blog/de/launch. The preview follows your edits, including changes to translations. Push, and the translation goes live with the original.

What a translation can set

The body is the translated post, with the same components, snippets and variables as any other. Images and other files in public/ are shared, so /images/cover.png works in every language. To show a different image, set image in the translation or link a different file in its body.

File names and URLs

The language in a file name is lowercase and can use .md or .mdx, independently of the original. With sections, translations follow each section’s path. In a translation, link to other posts in the same language, like ./guides or /blog/de/guides. While guides isn’t translated, /blog/de/guides sends readers to /blog/guides, and once you translate it, the same link opens the German page. /blog/guides always means the original. notra sites validate, notra dev and every build warn about links to pages that don’t exist in any language.

Check your translations

notra sites validate lists, for each language, how many posts are translated and which aren’t yet:
You don’t have to translate everything. With only some posts translated into German:

What readers and search engines get

  • Each language with at least one published translation gets the whole section below its path: a home page at /blog/de, an RSS feed at /blog/de/feed.xml, tag and author pages, Markdown versions, llms.txt and share images. Its home page lists only the translated posts.
  • Pages are in that language: <html lang> (with dir="rtl" for languages like Arabic), dates, the theme’s own text, like “Geschrieben von”, and your own text from localized.
  • A language switcher in the footer links each post to its translations, and to the other language’s home page where a post isn’t translated. A language whose only translations are hidden is offered on those posts only.
  • Translated pages link to each other with hreflang, plus x-default for the original, and each section’s sitemap lists every language with the same links, so search engines show readers the version in their language.
  • A page below /blog/de that exists in no language gets the 404 page in German.
The URL decides the language. Notra doesn’t guess it from the browser, because search engines and readers who follow a link should get the page the link names. Drafts of translations show in previews, like other drafts.

Remember a reader’s language

If your website already remembers the language a reader picked, for example in a cookie your language switcher sets, the blog can use it. Set languageCookie to the cookie’s name:
blog.json
  • A reader whose cookie is de and who opens an original page, like a shared link to /blog/launch, gets /blog/de/launch instead. Pages without a German translation stay in their language.
  • Choosing a language in the switcher sets the cookie to that language, like en or de, for the whole domain. The reader can always switch back, and your website sees the same choice.
  • Search engines don’t send cookies, so they always get the page the URL names, with its hreflang links.
  • The choice is shared both ways when the blog is served on your website’s domain, like acme.com/blog through a rewrite. On blog.acme.com, the blog reads a cookie your website sets on .acme.com, but a choice made in the blog’s switcher stays on blog.acme.com.
The cookie’s values are language tags as in translations and language. notra dev follows the cookie too, so you can try it locally.

Translate your site’s own text

The rest of a page’s text comes from blog.json: section titles, the navbar and footer, author titles, tag names, the banner and the 404 page. Give each translation its own under localized, keyed by a language in translations:
blog.json
Anything you leave out uses the setting itself, or the theme’s own text in that language when the setting isn’t set either. Settings without text, like colors, fonts, layouts and social links, are the same in every language. Variables work in the titles, descriptions and the banner. Your header, footer and slots get props.language, the language of the page like en or de, so they can show their own text in it:
slots/blog-hero.mdx
area.title, area.description and area.path already follow the translation, like /blog/de. A custom header or footer replaces the built-in one, with its switcher and the navbar or footer text from localized. props.languages lists the current page in each language, empty on a site without translations. Put data-language-switcher on your switcher so a click also sets the languageCookie:
footer.mdx

Fix build errors

The translation_key_inherited warning means a translation sets a shared field like date to a different value than the original. Change it in the original, or remove it from the translation. localized_author_unknown and localized_tag_unknown mean localized names an author or tag the site doesn’t have. See Limits and build errors for the other codes.

For coding agents

  • Read translations and language from blog.json before creating files, and add a missing language to translations first.
  • Create <path>.<language>.mdx next to the original, with a translated title, description and body. Don’t copy date, author or tags with new values; they always come from the original.
  • Link to /<section>/<language>/<slug> to stay in the translation’s language.
  • Put the translated navbar, footer, section titles, author titles and tag names in localized.<language> in blog.json, and use props.language for text in header.mdx, footer.mdx and slots.
  • Run notra sites validate and fix every error. Its coverage lines show what is still untranslated.
Last modified on November 21, 2026