HERON
Get started

Every language found in its own search

A multilingual website done right

A multilingual website done right gives each language its own address, tells search engines which pages are translations of each other with hreflang tags, lists every version in the sitemap, and lets visitors switch language on any page. Then each language is found in its own search results instead of competing with the others.

HERON does all of this from one line in site.yaml. Below: how language addresses work, what hreflang is, the usual mistakes, and how to add a language.

How language addresses work

The main language lives at the root, each other language under its own prefix. Addresses can be translated too.

WayExampleVerdict
Home//ru//de/
Services/services//ru/uslugi//de/leistungen/
One service/services/implants//ru/uslugi/implanty//de/leistungen/implantate/
Folder per languageexample.com/ru/Simple, one site, one domain authority. What HERON does
Subdomainru.example.comWorks, but counts more like a separate site
Language switch without a new addressexample.com/?lang=ru or a scriptAvoid: search engines see one language only

What hreflang does

hreflang is a set of tags in the page header that lists every language version of the page, like the table below. It tells Google which version to show to whom: the Russian page to people searching in Russian, the English one to the rest.

hreflangAddress
enhttps://example.com/services/
ruhttps://example.com/ru/uslugi/
x-defaulthttps://example.com/services/

Common mistakes

Automatic redirect by browser language

Search engine robots usually crawl without a language preference, so they never see the other versions. Offer a switcher instead.

Machine translation published as is

Thin, odd text hurts more than a missing page. Translate the key pages properly first.

One title for all languages

Every version needs its own title and description in its language.

A switcher that drops you on the home page

It should open the same page in the other language. When there is no translation, the item should be greyed out.

Missing return links in hreflang

See above: every version lists all the others.

Adding a language in HERON

  1. 1

    List the language

    In site.yaml: languages: [en, ru], and the main one in default_lang: en. Or tick it in the configurator.
  2. 2

    Add the pages

    Each language has its folder inside content/. A translation goes into the folder of its language with the same file name as the original, for example content/en/services.md and content/ru/services.md. That is how HERON knows which pages belong together.
  3. 3

    Translate addresses if you want

    Add slug: uslugi to the Russian page, and the address becomes /ru/uslugi/. Links in texts keep working: they are written once, by file name.
  4. 4

    Build

    HERON writes hreflang, the language switcher, a sitemap per language, and llms.txt per language.
  5. 5
  6. 6
  7. 7

One page in two languages

A translation is a copy of the file with the text rewritten. The file name stays the same, so HERON pairs the two versions.

content/en/services.md                content/ru/services.md
---                                   ---
title: "Dental services in Vienna"    title: "Стоматология в Вене: услуги"
h1: "Our services"                    h1: "Наши услуги"
description: "Treatment, implants…"   description: "Лечение, импланты…"
                                      slug: uslugi
---                                   ---

Addresses

/services/ and /ru/uslugi/. The main language has no prefix.

Links inside the text

Write them once, by file name: a link to /services/ on the Russian page becomes /ru/uslugi/ on its own.

A page not translated yet

Leave the file out. The language switch shows that language as unavailable on this page, and links to it from other pages lead to the version that exists.

What else changes per language

Site name and title suffix

Can differ per language.

Address, phone, company description

Written once with a language ending, such as address_ru, and shown in the right language.

Interface words

"Read more", menu labels and buttons come from a dictionary per language in the theme.

Structured data

schema.org markup is written in the language of each page.

Questions

Do I need a separate domain for each language?

No. A folder per language on one domain is simpler and keeps the search authority of the site together. Separate domains make sense when you run separate businesses per country.

What if a page is not translated yet?

The page simply is not in that language. The switcher shows the language as unavailable on that page, and hreflang does not mention it.

Can I write the second language first?

Yes. A page can exist only in the second language: it builds normally and goes into that language's sitemap, and the build report reminds you that the main version is missing. Only a site whose main language has no pages at all is stopped, because its home address would show an error.

How do I check hreflang works?

Open the page source and look for the hreflang lines, then open each address listed there: every one must answer and list the others back. Crawling tools that audit SEO check this for the whole site.

Does HERON translate the texts?

No. Translation is your text, or an AI agent's work that you check. HERON takes care of addresses, tags and the switcher.