blog/launch.mdx and its German translation blog/launch.de.mdx are published at /blog/launch and /blog/de/launch.
language instead.
Translate your first post
1
List your languages
Add the languages you translate into to Use language tags like
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
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:
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.txtand share images. Its home page lists only the translated posts. - Pages are in that language:
<html lang>(withdir="rtl"for languages like Arabic), dates, the theme’s own text, like “Geschrieben von”, and your own text fromlocalized. - 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, plusx-defaultfor 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/dethat exists in no language gets the 404 page in German.
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. SetlanguageCookie to the cookie’s name:
blog.json
- A reader whose cookie is
deand who opens an original page, like a shared link to/blog/launch, gets/blog/de/launchinstead. Pages without a German translation stay in their language. - Choosing a language in the switcher sets the cookie to that language, like
enorde, 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
hreflanglinks. - The choice is shared both ways when the blog is served on your website’s domain, like
acme.com/blogthrough a rewrite. Onblog.acme.com, the blog reads a cookie your website sets on.acme.com, but a choice made in the blog’s switcher stays onblog.acme.com.
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 fromblog.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 own header, footer and slots
Your header, footer and slots getprops.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
translationsandlanguagefromblog.jsonbefore creating files, and add a missing language totranslationsfirst. - Create
<path>.<language>.mdxnext to the original, with a translatedtitle,descriptionand body. Don’t copydate,authorortagswith 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>inblog.json, and useprops.languagefor text inheader.mdx,footer.mdxand slots. - Run
notra sites validateand fix every error. Its coverage lines show what is still untranslated.