Marmite supports multilingual sites through language streams. Each language becomes a stream with its own listing page and RSS feed, while translations are automatically cross-linked with "Also available in" navigation and hreflang SEO tags.
\nLanguages are auto-detected from content. Just set language: xx in your frontmatter or use subfolder naming conventions, and marmite handles the rest - no configuration required.
The language field in marmite.yaml (defaults to en) determines the site's default language. Content in the default language stays on index.html. Other languages get their own stream pages (pt.html, es.html) and RSS feeds (pt.rss, es.rss).
By default, language streams are labeled with their two-letter code (e.g., "pt", "es"). To set human-readable names, add an optional languages section to marmite.yaml:
language : en \nlanguages : \n pt : \n display_name : "Portugues" \n es : \n display_name : "Espanol" This follows the same pattern as streams: and series: - the config is purely cosmetic. Sites without any language content are completely unaffected.
There are four ways to organize multilingual content. All produce flat HTML output.
\n\n\nRECOMMENDED
\n
Group translations in a subfolder named after the base content's slug. Files prefixed with an ISO 639-1 language code are automatically detected and cross-linked:
\ncontent/hello/\n hello.md # Default language (en)\n pt-ola-mundo.md # Portuguese translation\n es-hola-mundo.md # Spanish translation\nThis generates:
\nhello.html - English post, listed on index.htmlpt-ola-mundo.html - Portuguese post, listed on pt.htmles-hola-mundo.html - Spanish post, listed on es.htmlAll three pages automatically show "Also available in" links to each other.
\nTip
\nThe subfolder can also have the date in it, e.g. content/2026-07-02-hello/ this way you don't have to specify date on each translation frontmatter.
Important
\nA subfolder is only treated as a translation group when it contains exactly one non-prefixed file (the original) and one or more language-prefixed files. If the subfolder has multiple non-prefixed files, marmite cannot determine which one is the original, so all files are treated as independent content and no translation linking occurs. Use translates: frontmatter for manual linking in that case.
\n\nRECOMMENDED
\n
If you have an existing flat site and want to add translations without moving original files, create a subfolder matching the existing content's slug:
\ncontent/\n hello.md # Existing flat file, slug: hello\n hello/\n pt-ola.md # Portuguese translation, auto-linked\nMarmite detects that the subfolder name hello matches the flat file's slug and links them as translations.
Important
\nSubfolder names must match the original post's slug (not the filename, but the resolved slug, sometimes taken from the title) to be automatically linked as translations.
\nEach translation points to the original content's slug using the translates field. Marmite builds the full bidirectional link network automatically:
--- \ntitle : Ola Mundo \ndate : 2024-01-01 \nlanguage : pt \ntranslates : hello \n--- This is simpler than maintaining a translations list on every file. Just set language and translates on each translation and marmite connects everything. Setting language to a value different from the site default automatically places the content on the corresponding language stream.
Set the language and translations explicitly in frontmatter:
\n--- \ntitle : Hello World \ndate : 2024-01-01 \nlanguage : en # can omit because it's the default language \ntranslations : \n - pt-ola # then you write a post with slug `ola` and language: set to `pt` \n - es-hola \n--- The translations field accepts a list of slugs. Marmite resolves each slug to the actual content, fills in the language code and display name, and creates bidirectional links. If post A lists post B as a translation, post B automatically gets a link back to post A.
Important
\nPrefer options 1 and 2 for auto discovery. Options 3 and 4 require explicit frontmatter but give you more control over the linking.
\nlanguageExplicitly set the content's language code:
\nlanguage : pt Usually not needed when using subfolder detection (Options 1 and 2). Use this when you need to set the language explicitly (Options 3 and 4).
\nWhen language is set to a value different from the site default and no explicit stream is set, marmite automatically uses the language as the stream. A post with language: pt will be published to pt.html.
translatesPoint a translation to the original content's slug:
\ntranslates : hello Marmite creates bidirectional links between the source and all its translations. Not needed with subfolder auto-discovery. See Option 3 above for details.
\ntranslationsManually link to translations by slug:
\ntranslations : \n - en-hello-world \n - es-hola-mundo Not needed when using subfolder auto-discovery (Options 1 and 2) or translates: (Option 3), since translations are linked automatically in those modes.
Content pages with translations show an "Also available in" section with links to each translation:
\nAlso available in: English, Espanol\nThe <head> section of translated content pages includes hreflang alternate link tags:
< link rel ="alternate " hreflang ="en " href ="https://example.com/en-hello-world.html "> \n< link rel ="alternate " hreflang ="es " href ="https://example.com/es-hola-mundo.html "> \n< link rel ="alternate " hreflang ="pt " href ="https://example.com/hello.html "> The <html lang="..."> attribute is also set correctly per page.
Language stream pages use the configured language name as the display name. A stream named pt automatically displays as "Portugues" without needing a separate streams.pt.display_name entry. You can override this by defining both languages and streams entries for the same code.
Marmite generates a languages.html page that lists all content organized by language. This page is always generated, even on monolingual sites (showing just the default language).
The page follows the same group template pattern as tags, authors, streams, series, and archives. Each language shows a collapsible list of its content with a link to the full language stream page.
\nLanguages are sorted alphabetically, with the site's default language appearing last in the list.
\nThe page heading can be changed in marmite.yaml:
languages_title : "Idiomas" In custom templates, the language_display_name Tera function returns the configured display name for a language code:
{{ language_display_name(language="pt") }}The group(kind="language") Tera function returns all content grouped by language:
{% for lang, posts in group(kind="language") %}\n < h2 > {{ language_display_name(language=lang) }}</ h2 > \n < p > {{ posts | length }} posts</ p > \n{% endfor %}en-) are detected and assigned to that language streamtranslates: pointers, and resolves frontmatter referencesTranslationRef entries containing the language code, display name, slug, and titleindex and appears on the main index.html pageessential-guide.md being detected as language es)series and a language stream - they work independentlyen-hello vs es-hola)language and translations for template display but do not appear on stream listing pages\n\n\n\n", "summary": "\"Write content in multiple languages with automatic translation linking, language stream pages, and hreflang SEO tags using marmite's language streams feature.\"", "date_published": "2026-07-02T00:00:00-00:00", "image": "media/language-streams/banner.jpg", "authors": [ { "name": "Bruno Rocha", "url": "https://go.rocha.social/@bruno", "avatar": "https://github.com/rochacbruno.png" } ], "tags": [ "docs", "features", "i18n", "multilingual" ], "language": "en" } ] }Please consider giving a ☆ on Marmite Github repository, that helps a lot!
\n