> For the complete documentation index, see [llms.txt](https://docs.themeupstudio.com/crimson/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.themeupstudio.com/crimson/multilingual/seo-and-hreflang-tags.md).

# SEO and Hreflang tags

### SEO note

Locale-domain switching currently affects the language switcher and browser-language redirect behavior.

{% hint style="danger" %}
**Crimson's `hreflang` tags are still static in the templates, so if you use locale-specific domains you should review and adjust your alternate-language SEO markup separately.**
{% endhint %}

### Editing `hreflang` Tags in Theme Code

Crimson's multilingual language switcher and locale-domain settings do **not** automatically rewrite every `<link rel="alternate" hreflang="...">` tag in the theme.

If you are using locale-specific domains or want to customize alternate-language SEO markup, you need to edit the theme templates manually.

{% hint style="danger" %}
Changing `USE_LOCALE_DOMAINS`, `LOCALE_DOMAINS`, or `LOCALE_DOMAIN_HOME_ONLY` in Code Injection does **not** automatically update all `hreflang` tags.
{% endhint %}

#### Important: there is no single global `hreflang` file

Crimson outputs the `hreflangs` block in the main layout, but the actual `<link rel="alternate">` tags are defined inside many individual template files.

This means editing only `partials/hreflangs.hbs` is **not enough**.

#### Where `hreflang` tags are defined

Common templates you may need to edit include:

* `home.hbs`
* `index.hbs`
* `post.hbs`
* `page.hbs`
* `tag.hbs`
* `author.hbs`
* `authors.hbs`
* `tags.hbs`
* `archive.hbs`
* `contact.hbs`
* `membership.hbs`
* `signin.hbs`
* `signup.hbs`
* `subscribe.hbs`
* `account.hbs`
* `error.hbs`

If you use alternate home or custom post templates, also review:

* `home-3-col.hbs`
* `home-carousel.hbs`
* `home-no-hero.hbs`
* `home-tag-layout-1-3.hbs`
* `home-tag-layout-2-2.hbs`
* `home-tag-layout-row.hbs`
* `custom-post-with-normal-toc-and-sidebar.hbs`
* `custom-post-with-sticky-toc.hbs`
* `custom-post-without-sidebar.hbs`
* `custom-post-without-toc.hbs`
* `custom-post-without-toc-and-sidebar.hbs`

#### What to look for

In each relevant template, look for this block:

```hbs
{{#contentFor 'hreflangs'}}
```

Inside that block, update the alternate URLs to match your real multilingual setup.

a. Example: `authors.hbs` for subfolder setup

If your multilingual setup uses subfolders, the alternate links can look like this:

```html
<link rel="alternate" href="{{@custom.main_locale_url}}/authors/" hreflang="{{@custom.main_locale}}" />
<link rel="alternate" href="{{@custom.main_locale_url}}/authors/" hreflang="x-default" />
<link rel="alternate" href="{{@custom.main_locale_url}}/hi/authors/" hreflang="hi" />
<link rel="alternate" href="{{@custom.main_locale_url}}/es/authors/" hreflang="es" />
```

b. Example: `authors.hbs` for locale-specific domains

If your multilingual setup uses separate domains or subdomains, replace the subfolder alternate links with your actual locale domains:

```html
<link rel="alternate" href="https://www.example.com/authors/" hreflang="en" />
<link rel="alternate" href="https://www.example.com/authors/" hreflang="x-default" />
<link rel="alternate" href="https://hi.example.com/authors/" hreflang="hi" />
<link rel="alternate" href="https://es.example.com/authors/" hreflang="es" />
```

c. Example: dynamic templates such as posts and pages

For dynamic templates such as posts, pages, tags, and author pages, you can keep the current path if the slug structure matches across languages:

```html
<link rel="alternate" href="https://www.example.com{{url}}" hreflang="en" />
<link rel="alternate" href="https://www.example.com{{url}}" hreflang="x-default" />
<link rel="alternate" href="https://hi.example.com{{url}}" hreflang="hi" />
<link rel="alternate" href="https://es.example.com{{url}}" hreflang="es" />
```

{% hint style="warning" %}
Only use path-preserving alternate links if the same slug exists in every language. If the translated page does not exist, the alternate link can point visitors and search engines to a 404 page.
{% endhint %}

#### When not to add `hreflang` links for inner pages

If you are using:

`LOCALE_DOMAIN_HOME_ONLY: true`

and you do not guarantee matching inner pages across languages, do not add alternate links for those inner URLs.

In that setup, it is usually safer to keep alternate links only for:

* homepages
* guaranteed translated landing pages
* pages that exist in every language

#### Important note about `error.hbs`

Several Crimson templates include a comment reminding you to copy matching `hreflang` changes to `error.hbs`. If you update your multilingual URL structure, review `error.hbs` as well so your 404 pages do not keep outdated alternate-language links.

#### Quick checklist

* Edit every template that outputs its own `hreflangs` block.
* Do not assume `partials/hreflangs.hbs` is the only file used.
* Keep `x-default` pointing to your main locale.
* Use exact locale domains if you switched away from `/hi/` and `/es/`.
* Only point to pages that really exist in the target language.
* Re-test home, post, page, tag, author, archive, contact, and error pages after the change.