Skip to content
50% OFF $299 $599
Lock in
§ 2.10.3 ARTICLE
Published VerifiedEvery 6 weeks Sources3 named Authored bySquareRank Team

Code Injection · § 2.10.3 · How-to

Squarespace hreflang via Code Injection — the multilingual install pattern

Squarespace has no native hreflang UI. Multilingual sites must inject hreflang link tags manually through Code Injection. The recommended placement is per-page Page Header Code Injection on every localised version of every page (Business plan or above), with a complete set of self-referencing and cross-referencing tags1. The pattern is mechanical; the failure modes are missing self-references and inconsistent region codes.

This leaf ships the production-ready hreflang block, documents the self-referencing rule that most multilingual installs get wrong, and covers the Search Console validation step. The cluster hub covers the broader Code Injection patterns; this leaf is the hreflang-specific install.

What hreflang is and why Squarespace needs the workaround

hreflang is the HTML link tag that tells Google which language and region a page is targeting. A site with English, German, and French versions of the same content uses hreflang to tell Google to serve the English page to English users, the German page to German users, and the French page to French users. Google supports three placement methods: HTML head, HTTP response headers, and XML sitemap. Squarespace does not expose any of the three in its SEO UI, so the install lives in Code Injection.

Google's hreflang documentation1 describes the three placement methods and the consequences of each. The HTML head method via Code Injection is the most reliable on Squarespace because the platform interpolates the panel content directly into the head element. The sitemap method requires editing sitemap.xml, which Squarespace generates automatically and does not allow direct edits to. The HTTP header method requires server access Squarespace does not provide.

The Code Injection hreflang pattern

A complete hreflang block lists every language and region variant of the page, including a self-reference, and an optional x-default fallback. The block goes in the head of every variant of the page; a three-language site has three pages, each carrying the same hreflang block with three link tags. The block must be identical on every variant or Google reports an asymmetric-tagging error.

HTML Per-page Page Header Code Injection — three-language hreflang 
 <!-- hreflang block for a page with EN, DE, and FR variants --> <!-- Paste the same block in Page Header Code Injection on all three pages --> <link rel="alternate" hreflang="en" href="https://yoursite.com/about/"> <link rel="alternate" hreflang="de" href="https://yoursite.com/de/about/"> <link rel="alternate" hreflang="fr" href="https://yoursite.com/fr/about/"> <link rel="alternate" hreflang="x-default" href="https://yoursite.com/about/">

Language codes follow ISO 639-1 (en, de, fr, es, it, ja, etc.). Region codes, when used, follow ISO 3166-1 alpha-2 (en-US, en-GB, de-DE, de-AT)2. The x-default tag tells Google which version to serve when no other variant matches the user's language preference; for most sites this is the English version.

Per-page injection on Business plan and above

Per-page Page Header Code Injection requires Business plan or above. The block above goes into Page Settings > Advanced > Page Header Code Injection on each of the three variant pages. The same three-link block lives on each variant. Squarespace's Header injection interpolates into the <head> element directly, which is Google's recommended placement for hreflang.

A multilingual Squarespace site with 20 pages and three language versions has 60 pages to inject hreflang into. The repetition is mechanical but error-prone. The cleanest pattern is to maintain a single hreflang block per page identity (the about page has one hreflang block; the pricing page has another) and paste the same block into the per-page Header on every language variant of that page. A spreadsheet with one column per page identity and one row per language is the standard tool.

Every hreflang block must include a self-reference: the page's own URL must appear in the block under the page's own language tag. The English page lists itself as the en variant; the German page lists itself as the de variant; the French page lists itself as the fr variant. Missing the self-reference is the single most common hreflang error Search Console reports, and it disables the entire hreflang relationship between the variants.

The error message in Search Console reads: "No return tags." Translation: page A says it has a German variant at URL B, but page B does not list page A as a variant. The fix is to add the missing self-reference and re-deploy.

Validate via Search Console after a recrawl

Once the hreflang blocks are live across every variant of every page, request a recrawl of each variant in Search Console (URL Inspection > Request Indexing). Within 7 to 14 days, the International Targeting report should populate. A clean install shows zero errors and a complete cross-reference matrix. The most common post-deployment fix is the missing-self-reference error; the second-most-common is mismatched URLs (the block on the German variant points at a URL that 404s).

View-source on each variant in a private browser window to confirm Squarespace interpolated the link tags into the head correctly. Search for hreflang= and confirm the right number of link tags appear in the head, before the closing </head> tag. If they appear in the body instead, the panel content was pasted into the Footer field by mistake; move it to the Header field and re-deploy.

Multilingual setup is a cluster-sized topic and this leaf is the Code Injection install only. For the full multilingual SEO context — URL structure decisions, content translation discipline, the language-versus-region question, and the Google Search Console country targeting overrides — the broader Squarespace SEO pillar contains the cross-cluster references.

Keep reading · § 2.10.3