hreflang for a site with the main language at the root: /, /en/ and /ua/
A common layout for a small multilingual site puts the main language at the root and the others under a prefix: / for Russian, /en/ for English, /ua/ for Ukrainian. One site built this way is https://cryptoexchangespain.com/en/. The hreflang tags for such a site take about twenty lines of code, and most mistakes come from three places.

1. The language code is not the folder name
The Ukrainian folder is /ua/, but the hreflang value is uk. UA is the ISO 3166 country code for Ukraine. Hreflang takes an ISO 639-1 language code, optionally followed by a region: uk, or uk-UA. A tag with hreflang="ua" is not a valid language code, and search engines ignore it.
The same trap exists for other pairs: the Czech language is cs, not cz, and Swedish is sv, not se.
2. Every page in the set must print the same block
Hreflang works only when the links are reciprocal: the Russian page points to the English one, and the English page points back. The simplest way to guarantee that is to compute the block from a base path, so all three pages of a set produce identical output.
const ORIGIN = "https://example.com";
const LOCALES = [
{ hreflang: "ru", prefix: "" },
{ hreflang: "en", prefix: "/en" },
{ hreflang: "uk", prefix: "/ua" },
];
// "/en/faq/" -> "/faq/", "/ua/" -> "/", "/faq/" -> "/faq/"
export function basePath(pathname) {
for (const { prefix } of LOCALES) {
if (prefix && (pathname === prefix + "/" || pathname.startsWith(prefix + "/"))) {
return pathname.slice(prefix.length);
}
}
return pathname;
}
export function hreflangTags(pathname) {
const base = basePath(pathname);
const links = LOCALES.map(({ hreflang, prefix }) => [hreflang, ORIGIN + prefix + base]);
links.push(["x-default", ORIGIN + base]);
return links
.map(([lang, href]) => `<link rel="alternate" hreflang="${lang}" href="${href}">`)
.join("\n");
}
The prefix check compares against prefix + "/", not just prefix. Otherwise a Russian page at /english-guide/ would lose its first three characters and turn into /lish-guide/.
3. x-default needs a decision
x-default tells search engines which page to show when none of the languages matches the user. With the main language at the root, the root is the natural choice, so here x-default repeats the Russian URL. A site whose root only redirects by browser language would point x-default at that redirecting page instead.
Tests
import assert from "node:assert/strict";
assert.equal(hreflangTags("/en/faq/"), hreflangTags("/faq/"));
assert.equal(hreflangTags("/ua/faq/"), hreflangTags("/faq/"));
assert.equal(basePath("/ua/"), "/");
assert.equal(basePath("/english-guide/"), "/english-guide/");
assert.ok(!hreflangTags("/faq/").includes('hreflang="ua"'));
All five pass on Node 24. For /ua/faq/ the function prints:
<link rel="alternate" hreflang="ru" href="https://example.com/faq/">
<link rel="alternate" hreflang="en" href="https://example.com/en/faq/">
<link rel="alternate" hreflang="uk" href="https://example.com/ua/faq/">
<link rel="alternate" hreflang="x-default" href="https://example.com/faq/">
One limit of this approach: it assumes every page exists in all three languages. If some pages are translated only partly, keep a list of the paths that exist per locale and print links only to those. A link to a missing page breaks the set for that page.
All rights reserved