Hreflang for Independent Multilingual Content: When Pages Are Not Translations

Canonical and hreflang answer different questions#

A canonical link identifies the preferred URL for the current page:

1
<link
2
  rel="canonical"
3
  href="https://example.com/en/posts/pagefind-multilingual-search-astro/"
4
>

An hreflang alternate identifies another localized version of the same content:

1
<link
2
  rel="alternate"
3
  hreflang="zh-Hant"
4
  href="https://example.com/posts/pagefind-multilingual-search-astro/"
5
>
6
<link
7
  rel="alternate"
8
  hreflang="en"
9
  href="https://example.com/en/posts/pagefind-multilingual-search-astro/"
10
>

Google Search Central describes hreflang as a way to identify localized variations of a page. It also expects every version to list the other versions, including itself. A one-way link is not a complete relationship.

The canonical on each localized page should normally point to that page itself. Do not canonicalize an English translation to the Traditional Chinese original; doing so conflicts with the intent to index both language versions.

Decide whether two articles are equivalents#

Use content intent, not shared tags, to make the decision.

For example, an English guide about preserving legacy URLs and a Chinese post about generating an Astro sitemap both belong to an Astro/SEO cluster. They are useful internal links, but they are not language alternatives. Each should remain self-canonical without an hreflang connection.

Represent translation as optional content data#

Folder names and matching slugs are weak evidence of equivalence. Use an explicit optional key in the content schema:

1
const postsCollection = defineCollection({
2
  schema: z.object({
3
    title: z.string(),
4
    lang: z.enum(["en", "zh-TW", "zh_TW", ""]).optional(),
5
    translationKey: z.string().trim().min(1).optional(),
6
  }),
7
});

Independent articles omit translationKey. A verified pair receives the same value:

1
# Traditional Chinese article
2
lang: zh-TW
3
translationKey: astro-i18n-routing

1
# English article
2
lang: en
3
translationKey: astro-i18n-routing

This model makes the editorial decision visible and reviewable. It also allows translated titles and different slugs without relying on filename equality.

Build alternates only for complete pairs#

Group posts by non-empty translationKey, then require one unambiguous entry for each supported locale.

1
type Locale = "zh-TW" | "en";
2

3
for (const post of posts) {
4
  const key = post.data.translationKey?.trim();
5
  if (!key) continue;
6

7
  const locale = normalizeLocale(post.data.lang);
8
  const group = groups.get(key) ?? new Map<Locale, Post>();
9

10
  if (group.has(locale)) {
11
    throw new Error(`Duplicate translation key: ${key} (${locale})`);
12
  }
13

14
  group.set(locale, post);
15
  groups.set(key, group);
16
}

When a group has both zh-TW and en, create two alternates and pass them into the page layout. When only one side exists, emit nothing. This avoids publishing a relation to a missing URL.

The resulting Astro layout can render absolute URLs:

1
{alternates.map((alternate) => (
2
  <link
3
    rel="alternate"
4
    hreflang={alternate.hreflang}
5
    href={new URL(alternate.path, Astro.site).href}
6
  />
7
))}

Fail the build when the same locale uses one translation key twice. Choosing the first match would make the output depend on collection order and could connect the wrong article.

Keep independent English articles unpaired#

For an English-first experiment, it is acceptable for every initial article to have no equivalent Chinese page. Give each English URL:

• an absolute self-canonical containing /en/posts/;
• html lang="en";
• BlogPosting.inLanguage set to en;
• its own English title, description, and body;
• no article-level hreflang until an equivalent page exists.

These technical boundaries work alongside the URL and query design in Build an Astro Multilingual Blog Without Migrating Existing URLs. If the site uses Pagefind, the same root language value can also keep multilingual search results separated.

Verify the generated HTML#

Check output files after the production build. Source components cannot prove which conditional tags were rendered.

1
pnpm build
2

3
rg 'rel="canonical"' dist/en/posts
4
rg 'hreflang=' dist/en/posts
5
rg '"inLanguage":"en"' dist/en/posts
6
rg '/en/posts/en/' dist

For a pilot containing only independent English articles, the hreflang search should return no matches. The double-prefix search should also be empty.

If you later add a translation pair, inspect both generated pages and verify that:

1. both pages remain self-canonical;
2. both list the English and Traditional Chinese alternates;
3. alternate URLs are absolute and return successful pages;
4. no third page shares the key in either locale.

The editorial test comes before the markup test: if two articles do not solve the same reader problem with equivalent main content, do not pair them. A shared topic is an internal-link relationship, not automatically a language-alternate relationship.

FAQ#