> ## Documentation Index
> Fetch the complete documentation index at: https://www.usenotra.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Translations

> Publish posts and changelog entries in more than one language, at the same slug below a language path.

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`.

```text theme={"system"}
blog.json                 { "translations": ["de", "fr"] }
blog/launch.mdx        →  /blog/launch
blog/launch.de.mdx     →  /blog/de/launch
blog/launch.fr.mdx     →  /blog/fr/launch
```

If your whole site is in one language other than English, you don't need translations. Set [`language`](https://www.usenotra.com/docs/sites/customize/seo#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:

```json blog.json theme={"system"}
{
  "name": "Acme",
  "language": "en",
  "translations": ["de", "fr"]
}
```

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:

```bash theme={"system"}
cp blog/launch.mdx blog/launch.de.mdx
```

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:

```mdx blog/launch.de.mdx theme={"system"}
---
title: "Acme Flow ist da"
description: "Ein ruhigerer Weg, Produkt-Updates zu veröffentlichen."
---

Heute starten wir **Acme Flow**.
```

**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

| Field | In a translation |
| - | - |
| `title` | Required |
| `description`, `image`, `imageAlt` | Optional, the original's otherwise |
| `updated` | Optional on blog posts, for when the translation last changed |
| `draft` | Optional. A draft original keeps all of its translations unpublished too |
| `date`, `author`, `tags`, `version`, `featured`, `hidden`, `noindex` | Always the original's, so dates, authors, tag pages and visibility match in every language. Leave them out, or keep them as copied. A different value is ignored with a warning. To translate author titles and tag names, use [`localized`](#translate-your-sites-own-text) |

The body is the translated post, with the same [components](https://www.usenotra.com/docs/sites/components/overview.md), snippets and [variables](https://www.usenotra.com/docs/sites/reference/blog-json.md#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

| File | URL |
| - | - |
| `blog/launch.de.mdx` | `/blog/de/launch` |
| `blog/2026/launch.de.mdx` | `/blog/de/2026/launch` |
| `blog/guides/index.de.mdx` | `/blog/de/guides` |
| `blog/launch.pt-br.mdx`, with `"pt-BR"` in `translations` | `/blog/pt-br/launch` |
| `changelog/2026-10-01.de.mdx` | `/changelog/de/2026-10-01` |
| `changelog/2026-10-01.de.mdx`, with the changelog at `/` | `/de/2026-10-01` |

The language in a file name is lowercase and can use `.md` or `.mdx`, independently of the original. With [`sections`](https://www.usenotra.com/docs/sites/reference/blog-json#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:

```bash theme={"system"}
notra sites validate
```

```text theme={"system"}
  de: blog 4 of 5, changelog 2 of 2 (not translated: blog/guides)
  fr: blog 1 of 5, changelog 0 of 2 (not translated: blog/guides, blog/hello, blog/launch, blog/pricing, changelog/v1 and 1 more)
✔ 7 entries, 7 translations, 21 files look good
```

You don't have to translate everything. With only some posts translated into German:

| Where | What readers get |
| - | - |
| `/blog/launch`, `/blog/guide` | Every original, as before |
| `/blog/de/launch` | The German post |
| `/blog/de/guide`, not translated | Sent to `/blog/guide` |
| `/blog/de` | Only the German posts, with categories and tags that have German posts |
| Language switcher on `/blog/guide` | "Deutsch" opens `/blog/de`, the German home |
| Previous and next on a German post | Other German posts |
| `hreflang` and the sitemap | Only pages that exist in both languages |
| A reader with the [language cookie](#remember-a-readers-language) on `/blog/guide` | Stays on the original |
| A section without German posts, like the changelog | No `/changelog/de`; German pages link to the original |

## 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](https://www.usenotra.com/docs/sites/customize/seo.md#language), like "Geschrieben von", and [your own text](#translate-your-sites-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](https://www.usenotra.com/docs/sites/posts.md#hidden-pages) 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](https://www.usenotra.com/docs/sites/previews.md), 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:

```json blog.json theme={"system"}
{
  "translations": ["de"],
  "languageCookie": "site_language"
}
```

* 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](https://www.usenotra.com/docs/sites/domains/subpath.md). 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`:

```json blog.json theme={"system"}
{
  "name": "Acme",
  "translations": ["de"],
  "blog": { "title": "Acme Blog", "description": "Notes from the Acme team." },
  "navbar": { "cta": { "label": "Sign up", "href": "https://acme.com/signup" } },
  "authors": { "jan": { "name": "Jan", "title": "Engineer" } },
  "localized": {
    "de": {
      "blog": { "title": "Acme Blog auf Deutsch", "description": "Neues vom Acme-Team." },
      "navbar": { "cta": { "label": "Registrieren", "href": "https://acme.com/de/signup" } },
      "authors": { "jan": { "title": "Entwickler" } },
      "tags": { "Product": "Produkt" },
      "errors": { "404": { "title": "Diese Seite gibt es nicht" } }
    }
  }
}
```

| Setting | What it replaces on the translated pages |
| - | - |
| `description` | The site description |
| `blog.title`, `blog.description`, `blog.hero.eyebrow` | The blog's title, the line under it and the [line above it](https://www.usenotra.com/docs/sites/customize/layouts.md). The title and description are also used in page titles, the feed, `llms.txt` and share images |
| `changelog.title`, `changelog.description`, `changelog.hero.eyebrow` | The same for the changelog |
| `navbar.links`, `navbar.cta`, `navbar.areas` | The [navbar](https://www.usenotra.com/docs/sites/customize/navigation.md#navbar) links, button and section links, in the same format. Each replaces the whole setting, so links can also point to your website's pages in that language |
| `footer.links` | The [footer](https://www.usenotra.com/docs/sites/customize/navigation.md#footer) links, in the same format |
| `authors.<id>` | The `title`, `bio` or `name` of an author from [`authors`](https://www.usenotra.com/docs/sites/posts#authors) |
| `tags` | Tag names, keyed by the tag as your posts write it. Tag pages keep their URLs, like `/blog/de/tags/product` |
| `banner.content` | The [banner](https://www.usenotra.com/docs/sites/customize/navigation.md#banner) text, when the site has a banner |
| `errors.404.title`, `errors.404.description` | The [404 page](https://www.usenotra.com/docs/sites/customize/seo.md#404-page) text |
| `thumbnails.label` | The label on [share images](https://www.usenotra.com/docs/sites/customize/seo.md#share-images) |

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](https://www.usenotra.com/docs/sites/reference/blog-json.md#variables) work in the titles, descriptions and the banner.

## Your own header, footer and slots

Your [header, footer and slots](https://www.usenotra.com/docs/sites/match-your-website.md) get `props.language`, the language of the page like `en` or `de`, so they can show their own text in it:

```mdx slots/blog-hero.mdx theme={"system"}
<h1>{props.language === "de" ? "Der Acme Blog" : "The Acme Blog"}</h1>
<p>{area.description}</p>
```

`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`](#remember-a-readers-language):

| Field | Value |
| - | - |
| `language` | The language tag, like `de` |
| `name` | The language's name in itself, like "Deutsch" |
| `href` | The page in that language, or that language's home page when the page isn't translated |
| `current` | `true` for the language of the current page |
| `translated` | `false` when `href` is the home page because the page isn't translated |

```mdx footer.mdx theme={"system"}
{props.languages.length > 1 && (
  <nav aria-label="Languages" data-language-switcher>
    {props.languages.map((entry) =>
      entry.current ? <span>{entry.name}</span> : <a href={entry.href} hreflang={entry.language}>{entry.name}</a>
    )}
  </nav>
)}
```

## Fix build errors

| Code | What it means | Fix |
| - | - | - |
| `translation_language_unknown` | The language in a file name isn't in `translations` | Add it to `translations`, or fix the typo the message suggests, like `launch.de.mdx` for `launch.da.mdx` |
| `translation_original_missing` | There's no original with the same path | Add the original, or rename the translation to match it |
| `translation_title_missing` | The translation has no `title` | Add a translated `title` |
| `frontmatter_yaml` | The translation's frontmatter isn't valid YAML | Fix the line the message names, often a `:` in an unquoted title |
| `translation_path_conflict` | A file or folder in the section has a language's name, like `blog/de/`, or a translation's path is another section's, like the blog's `/de` when the changelog is at `/de` | Rename the file or folder, or move the other section with [`sections`](https://www.usenotra.com/docs/sites/reference/blog-json#sections) |
| `translation_language_default` | `translations` lists the site's own `language` | Remove it from `translations` |
| `localized_language_unknown` | `localized` has a language that isn't in `translations` | Add it to `translations`, or remove its text |
| `slug_invalid` | A dot in a file name isn't a language, like `node.js.mdx` | Use dashes, like `node-js.mdx` |

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](https://www.usenotra.com/docs/sites/reference/limits.md#common-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.