Svelte 5 : hydration_html_changed when using `$_` or `$json` and `{@html}`

[marc-bouvier]

Describe the bug

In Svelte 5, when svelte-i18n translations ($_() or $json()) are used along with {@html } then it fallbacks to default language.

I wonder if I am doing something that should work or If I misunderstood how to use Svelte and svelte-i18n.

Screenshot to illustrate

Fallbacks to default (french)

{#each $json('philosophy.paragraphs') as paragraph}
   <p>{@html paragraph}</p>
{/each}
   <p>{@html $_('singular.html')}</p>
   
<hr/>

Does not fallback

{#each $json('philosophy.paragraphs') as paragraph}
   <p>{paragraph}</p>
{/each}

<p>{$_('singular.html')}</p>

Default translation file sample `fr.json` :

{
	"page": {
		"title": "🇫🇷 svelte-i18n avec $json() et {@html}"
	},
	"philosophy": {
		"title": "🇫🇷 Notre philosophie",
		"paragraphs": [
			"🇫🇷 Français Foo <strong>Bar</strong>", 
			"🇫🇷 Baz <strong>Polop ! </strong>"
		]
	},
"singular.html":"🇫🇷 Phrase seule avec des <strong>éléments HTML</strong>."
}

Translation file sample `en.json` :

{
	"page": {
		"title": "🇬🇧 svelte-i18n with $json() and {@html}"
	},
	"philosophy": {
		"title": "🇬🇧Our philosophy",
		"paragraphs": [
			"🇬🇧 English Foo <strong>Bar</strong>", 
			"🇬🇧 Baz <strong>Polop ! </strong>"
		]
	},
	"singular.html":"🇬🇧 Singular sentence with <strong>HTML elements</strong>."
}

Logs

Browser logs

+page.svelte:47 [svelte] hydration_html_changed The value of an `{@html ...}` block near src/​routes/​+page.svelte:52:1 changed between server and client renders. The client value will be ignored in favour of the server value

To Reproduce

Repository : https://github.com/marc-bouvier/svelte-i18n-json-at-html

• Checkout the repository and run npm start.
• Open http://localhost:5173
• Set your browser language to english.

In this application default language is french. It will fallback to french by default.

Expected behavior

When your main language is english, the paragraphs below should be in english... But, they fallback to default language : french.

Stacktraces

Stack trace : "hydration_html_changed"

+page.svelte:47 [svelte] hydration_html_changed The value of an `{@html ...}` block near src/​routes/​+page.svelte:52:1 changed between server and client renders. The client value will be ignored in favour of the server value
warn @ client.js?v=3056b061:2682

hydration_html_changed @ chunk-6CYEJA6J.js?v=3056b061:343

check_hash @ chunk-TQUCQ5FU.js?v=3056b061:1007

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:1047

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

branch @ chunk-6CYEJA6J.js?v=3056b061:1325

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:1028

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

block @ chunk-6CYEJA6J.js?v=3056b061:1322

html @ chunk-TQUCQ5FU.js?v=3056b061:1016

_page @ +page.svelte:47

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:251

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

branch @ chunk-6CYEJA6J.js?v=3056b061:1325

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:245

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

block @ chunk-6CYEJA6J.js?v=3056b061:1322

wrapper @ chunk-TQUCQ5FU.js?v=3056b061:238

(anonymous) @ root.svelte:48

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:1191

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

branch @ chunk-6CYEJA6J.js?v=3056b061:1325

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:1191

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

block @ chunk-6CYEJA6J.js?v=3056b061:1322

component @ chunk-TQUCQ5FU.js?v=3056b061:1184

(anonymous) @ root.svelte:48

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:1143

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:1131

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

branch @ chunk-6CYEJA6J.js?v=3056b061:1325

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:1129

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

block @ chunk-6CYEJA6J.js?v=3056b061:1322

snippet @ chunk-TQUCQ5FU.js?v=3056b061:1120

_layout @ +layout.svelte:10

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:251

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

branch @ chunk-6CYEJA6J.js?v=3056b061:1325

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:245

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

block @ chunk-6CYEJA6J.js?v=3056b061:1322

wrapper @ chunk-TQUCQ5FU.js?v=3056b061:238

(anonymous) @ root.svelte:46

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:1191

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

branch @ chunk-6CYEJA6J.js?v=3056b061:1325

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:1191

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

block @ chunk-6CYEJA6J.js?v=3056b061:1322

component @ chunk-TQUCQ5FU.js?v=3056b061:1184

(anonymous) @ root.svelte:46

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:558

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

branch @ chunk-6CYEJA6J.js?v=3056b061:1325

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:558

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

block @ chunk-6CYEJA6J.js?v=3056b061:1322

if_block @ chunk-TQUCQ5FU.js?v=3056b061:539

Root @ root.svelte:42

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:251

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

branch @ chunk-6CYEJA6J.js?v=3056b061:1325

(anonymous) @ chunk-TQUCQ5FU.js?v=3056b061:245

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

block @ chunk-6CYEJA6J.js?v=3056b061:1322

wrapper @ chunk-TQUCQ5FU.js?v=3056b061:238

(anonymous) @ chunk-2CUNGZBJ.js?v=3056b061:526

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

branch @ chunk-6CYEJA6J.js?v=3056b061:1325

(anonymous) @ chunk-2CUNGZBJ.js?v=3056b061:506

update_reaction @ chunk-6CYEJA6J.js?v=3056b061:1722

update_effect @ chunk-6CYEJA6J.js?v=3056b061:1813

create_effect @ chunk-6CYEJA6J.js?v=3056b061:1193

effect_root @ chunk-6CYEJA6J.js?v=3056b061:1267

_mount @ chunk-2CUNGZBJ.js?v=3056b061:504

hydrate @ chunk-2CUNGZBJ.js?v=3056b061:453

Svelte4Component @ chunk-2CUNGZBJ.js?v=3056b061:696

(anonymous) @ chunk-2CUNGZBJ.js?v=3056b061:654

initialize @ client.js?v=3056b061:447

_hydrate @ client.js?v=3056b061:2429

await in _hydrate

start @ client.js?v=3056b061:306

(anonymous) @ (index):32

Promise.then

(anonymous) @ (index):31

Information about your project:

• Your browser and the version: Brave [Version 1.71.123 Chromium: 130.0.6723.116 (Official Build) (arm64]

• Your operating system: MacOS Sequoia 15.0 (24A335)

• svelte-i18n version : 4.0.1

• Whether your project uses Webpack or Rollup : Vite

• Svelte version : 5.2.0

[th0rgall]

I had the same issue (in Svelte 4). I think it is purely related to the way Svelte hydrates {@html } tags in combination with SvelteKit's adapter-static. This is probably not a svelte-18n library bug.

The problem

If you generate your pages with adapter-static, you will generate them with the fallback French content everywhere because the build-time "server" render step doesn't set an English accept-language header (or any headers). Inspect the HTML in your dist folder to confirm.

When Svelte hydrates the page in an English browser, the initial value of any rendered store value like {$_('my.key')} will be English (even before onMount is called). This creates a mismatch between the static French HTML content, and the English content generated by Svelte's client-side hydration render step.

Svelte is able to repair this for normal store values (replace the HTML DOM value with it's JS-generated value). However, Svelte can not repair this mismatch for {@html } interpolations.

Svelte 5 officially can not do this, it's documented: https://svelte.dev/docs/svelte/v5-migration-guide#Other-breaking-changes-img-src-and-html-hydration-mismatches-are-not-repaired

Apparently, Svelte 4 was supposed to be able to do this, but it anyway didn't seem to work (see the bug report sveltejs/kit#12832 closed as "not planned", because Svelte 5 dropped the feature, and the team didn't want to patch this in Svelte 4)

Solutions

You have some options:

1. Only load the browser's accept-language in onMount. This is what I'm doing in my project for now (commit). In this way, you set svelte-i18n to always initialize with with the default language, and then you load/swap the language only after the components have mounted and hydrated. This might lead to a flash of French content, but you'd anyway have that effect even if Svelte supported the {@html } repair.
2. You could generate different static pages for different languages, and use path-based localization (/en/about-us and /fr/a-propos), like this project does for example: https://github.com/gpxstudio/gpx.studio - I want to work towards this in my project.
3. You could use full SSR without adapter-static, so that Svelte doesn't have to hydrate a static page, but can immediately use the browser's accept-language language on the first server-side render step, by whichthe mismatch is avoided on the client-side hydration step.

[marc-bouvier]

@th0rgall Thank you so much for having taken of your time to answer with details and options.

We will consider the options you have proposed.

[superafroman]

We use adapter-node and had the same issue in one of our apps. For anyone else coming across this, it's because we hadn't completed the SvelteKit setup as spec'd here: https://github.com/kaisermann/svelte-i18n/blob/main/docs/Svelte-Kit.md

Specifically this app was missing the server hook, which ensures that SSR uses the correct locale:

import type { Handle } from '@sveltejs/kit';
import { locale } from 'svelte-i18n';

export const i18nHandle: Handle = async ({ event, resolve }) => {
  const lang = event.request.headers.get('accept-language')?.split(',')[0];
  if (lang) {
    locale.set(lang);
  }
  return resolve(event);
};