Reading this document’s <head> ...
This helper never builds a URL by stripping or guessing a slug. It asks Ghost (via {{#get}}) for the posts that actually share this article’s grouping tag #grp-<topic>.
Ghost only returns published posts, and {{url absolute="true"}} is Ghost’s own URL for each. So if the Arabic version is not written, Ghost returns no Arabic post, no ar alternate is emitted, and there is no Arabic URL anywhere that could 404.
Open the energy story to see this live: English and Russian alternates are present, Arabic is simply absent. Every emitted href, and the self-canonical, is a real published post’s real 200 URL.
# routes.yaml - multilingual routing for a single Ghost (Pro) instance.
# Upload at Settings > Labs > Routes (or via the Admin API). No URL rewriting needed:
# every language version is a normal published post that resolves at its own real URL.
#
# Tag scheme (internal tags, created with a leading # in the editor):
# #ru, #ar language tags. Ghost auto-slugs them hash-ru, hash-ar.
# English (default) posts carry NEITHER language tag.
# #grp-<topic> grouping tag (slug hash-grp-<topic>) placed on EVERY language
# version of the same article so the versions can find each other.
# Translations are linked by this tag, never by stripping a slug.
routes:
collections:
# English (default). Everything that is NOT tagged #ru or #ar.
/:
permalink: /{slug}/
template: index
filter: tag:-hash-ru+tag:-hash-ar
# Russian. /ru/<slug>/
/ru/:
permalink: /ru/{slug}/
template: index-ru
filter: tag:hash-ru
# Arabic (right-to-left). /ar/<slug>/
/ar/:
permalink: /ar/{slug}/
template: index-ar
filter: tag:hash-ar
# Adding a future language (e.g. French) is a localized, no-rebuild change:
# 1. add one collection block below, filter: tag:hash-fr, template: index-fr
# 2. extend the default collection filter to also exclude it: tag:-hash-ru+tag:-hash-ar+tag:-hash-fr
# 3. add a ~6-line index-fr.hbs (sets the language blocks, reuses the shared post-list partial)
# 4. add one row to partials/language-registry.hbs
# The hreflang helper, self-canonical and the language switcher keep working untouched.
#
# /fr/:
# permalink: /fr/{slug}/
# template: index-fr
# filter: tag:hash-fr
taxonomies:
tag: /tag/{slug}/
author: /author/{slug}/
{{!--
partials/hreflang.hbs
404-safe hreflang + x-default for a single multilingual Ghost (Pro) instance.
Include in default.hbs <head>, AFTER {{ghost_head}}. ghost_head already emits the
SELF-REFERENCING canonical for the current URL (Ghost's default), so each version
canonicals to itself. We never override it to point at the English version.
How it stays 404-safe (the whole point):
This helper NEVER builds a URL by stripping or guessing a slug. It asks Ghost, via
{{#get}}, for the posts that actually share this article's grouping tag. Ghost only
ever returns published posts, and {{url absolute="true"}} is Ghost's own URL for each
one. So if the Arabic version is not written yet, Ghost returns no Arabic post, this
helper emits no `ar` alternate, and there is no Arabic URL anywhere that could 404.
Every hreflang href (and the canonical) is the real, 200-resolving URL of a real post.
Tag scheme: #ru/#ar are language tags (slugs hash-ru/hash-ar); English carries neither.
#grp-<topic> is the grouping tag (slug hash-grp-<topic>) shared by every version.
--}}
{{#is "post"}}{{#post}}
{{#foreach tags}}
{{!-- Act on the grouping tag only. {{match}} can't test a prefix, so a scoped
{{#get "tags"}} does it: it returns this tag only when its slug starts hash-grp-. --}}
{{#get "tags" filter="slug:{{slug}}+slug:~^'hash-grp'" limit="1" as |grp|}}
{{#foreach grp}}
{{#get "posts" filter="tag:{{slug}}" include="tags" limit="all" order="published_at asc" as |versions|}}
{{#foreach versions}}
{{#has tag="#ar"}}
<link rel="alternate" hreflang="ar" href="{{url absolute="true"}}" />
{{else}}{{#has tag="#ru"}}
<link rel="alternate" hreflang="ru" href="{{url absolute="true"}}" />
{{else}}
<link rel="alternate" hreflang="en" href="{{url absolute="true"}}" />
<link rel="alternate" hreflang="x-default" href="{{url absolute="true"}}" />
{{/has}}{{/has}}
{{/foreach}}
{{/get}}
{{/foreach}}
{{/get}}
{{/foreach}}
{{/post}}{{/is}}