bug: static rendered html lang is always "en" + missing "hreflang" #5086

bguiz · 2026-04-02T09:10:31Z

bguiz
Apr 2, 2026

Steps to reproduce

In docs.json configure multiple languages via navigation.languages based on instructions in https://www.mintlify.com/docs/guides/internationalization
- Includes Korean language pages under /ko/*

Problem 1

Visit https://{YOUR_MINTLIFY_DOMAIN}/ko in Chrome
Use "View Source" to view static render from server
Use DevTools to view dynamic render in browser (DOM)
Observe that the dynamic render has the <html /> tag's lang property's value as ko --> Correct behaviour
Observe that the static render has the <html /> tag's lang property's value as en --> Wrong behaviour

Problem 2

Visit https://{YOUR_MINTLIFY_DOMAIN}/ in Chrome
Use "View Source" to view static render from server
Observe that <link rel="alternate" hreflang="ko" href="{YOUR_MINTLIFY_DOMAIN}/ko/" /> is not present
Observe that <link rel="alternate" hreflang="x-default" href="{YOUR_MINTLIFY_DOMAIN}/" /> is not present

Observations

Problem 1

Therefore conclusion is that there is a bug where the pages are initially rendered with the default/ canonical language (en) and only updated in the browser
This is problematic from an SEO/ GEO perspective as it could result in:
- De-ranking due to duplicate content penalties
- Confusion (which page to use?) when gen AI tools are retrieving/ citing information from the site
- Excessive context bloat (resulting in poor quality result) when gen AI tools are retrieving/ citing information from the site

Problem 1 - Actual Outcome

Static render from server (wrong):

<!DOCTYPE html><html lang="en" class="__variable_47c970 __variable_3bbdad dark" data-banner-state="visible" data-assistant-state="closed" data-page-mode="none">

Dynamic render in browser (correct):

<!DOCTYPE html><html lang="ko" class="__variable_47c970 __variable_3bbdad twoslash-dark dark" data-banner-state="hidden" data-assistant-state="closed" data-page-mode="none" style="color-scheme: dark; --assistant-sheet-width: 0px; --banner-height: 0px; --sidenav-move-up: 0px;">

Problem 1 - Expected Outcome

Static render from server (correct):

<!DOCTYPE html><html lang="ko" class="__variable_47c970 __variable_3bbdad dark" data-banner-state="visible" data-assistant-state="closed" data-page-mode="none">

Dynamic render in browser (correct):

<!DOCTYPE html><html lang="ko" class="__variable_47c970 __variable_3bbdad twoslash-dark dark" data-banner-state="hidden" data-assistant-state="closed" data-page-mode="none" style="color-scheme: dark; --assistant-sheet-width: 0px; --banner-height: 0px; --sidenav-move-up: 0px;">

Problem 2

This is problematic from an SEO/ GEO perspective as it could result in:
- De-ranking due to duplicate content penalties

Problem 2 - Actual outcome

<link rel="canonical" href="{YOUR_MINTLIFY_DOMAIN}/ko"/>
<link rel="alternate" type="application/xml" href="/sitemap.xml"/>

Problem 2 - Expected Outcome

<link rel="canonical" href="{YOUR_MINTLIFY_DOMAIN}/ko"/>
<link rel="alternate" type="application/xml" href="/sitemap.xml"/>
<link rel="alternate" hreflang="en" href="{YOUR_MINTLIFY_DOMAIN}/" />
<link rel="alternate" hreflang="ko" href="{YOUR_MINTLIFY_DOMAIN}/ko/" />
<link rel="alternate" hreflang="x-default" href="{YOUR_MINTLIFY_DOMAIN}/" />

Context

I have translated pages in my docs where:

/*: English
/ko/*: Korean
... etc

References

https://www.semrush.com/blog/hreflang-attribute-101/

bguiz · 2026-06-15T04:01:38Z

bguiz
Jun 15, 2026
Author

bump ^.
could someone from @mintlify at least triage this?

0 replies

rodrigocaetanosilva · 2026-08-25T02:09:36Z

rodrigocaetanosilva
Aug 25, 2026

Adding a data point for the single-language case, which I think is the part of this that is still broken.

Our docs site is published entirely in Brazilian Portuguese. There is no English version and none is planned. The rendered HTML is <html lang="en"> on every page.

What we tried, and the result:

navigation.products only, no languages block at all. This is the natural config for a monolingual site. Result: lang="en".
Wrapping the products in a single-item navigation.languages, i.e. [{ "language": "pt-BR", "default": true, "products": [...] }]. The build validates, all URLs stay exactly the same (no /pt-BR prefix is added), and lang is still en.

I also checked the published docs.json schema for any top-level locale, lang, dir or i18n field. There is none, and seo.metatags only emits <meta> tags, so it cannot reach the <html> element.

This lines up with the root cause described in this thread: the document language appears to be derived from the URL locale prefix, and since the default language never gets a prefix, it falls back to a hardcoded en. For a multi-language site that at least gives you correct lang on the non-default locales. For a site that only ever has one language, and that language is not English, there is currently no way to get it right.

The impact is not cosmetic. Screen readers use lang to pick pronunciation rules, so an entire Portuguese site gets read with English phonetics, and search engines use it as a language signal.

Would it be possible to honor language on a single-item languages array (or add a top-level field) so that monolingual non-English sites can set the document language without inventing a second locale just to push the real one into a URL prefix?

0 replies

Navigation Menu

Mintlify

bug: static rendered html lang is always "en" + missing "hreflang" #5086

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 2 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Mintlify

bug: static rendered html lang is always "en" + missing "hreflang" #5086

Uh oh!

Uh oh!

bguiz Apr 2, 2026

Steps to reproduce

Problem 1

Problem 2

Observations

Problem 1

Problem 1 - Actual Outcome

Problem 1 - Expected Outcome

Problem 2

Problem 2 - Actual outcome

Problem 2 - Expected Outcome

Context

References

Replies: 2 comments

Uh oh!

bguiz Jun 15, 2026 Author

Uh oh!

rodrigocaetanosilva Aug 25, 2026

bguiz
Apr 2, 2026

bguiz
Jun 15, 2026
Author

rodrigocaetanosilva
Aug 25, 2026