Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

perf(i18n): skip identical catalog writes so a heading keeps its real LCP

nirholas630cf7ce7e2c
diff --git a/src/i18n.js b/src/i18n.js
index 2c9cfa833..34fe9659c 100644
--- a/src/i18n.js
+++ b/src/i18n.js
@@ -101,6 +101,31 @@ function scriptOwns(el) {
return el.getAttribute('data-i18n-owned') === '1';
}
+// Writing a value a node already holds is not free, and on the default locale
+// almost every write is exactly that: the markup ships the English source and
+// the English catalog hands the same string back. The cost is not the assignment
+// but what it does to Largest Contentful Paint. Replacing an element's text
+// destroys the text node and creates a new one, and Chrome scores that as a
+// fresh LCP candidate at the moment it happens, so the catalog pass (which lands
+// after an async /api/locale fetch, several seconds in on a phone) re-dated
+// every page's LCP to itself. Measured on a Pixel 5 over slow 4G against
+// production on 2026-09-08: `/` reported LCP 10,188 ms on `h1.hero-h`, a static
+// heading, against an FCP of 2,336 ms; `/docs/start-here` 5,168 ms on a `<p>`.
+// The pixels never changed. Skipping identical writes leaves the original text
+// node in place, so LCP stays where the paint actually was.
+//
+// Markup needs a normalizing pass before it can be compared: the browser rewrites
+// attribute quoting, entity forms and self-closing tags on the way in, so a raw
+// catalog string never equals the innerHTML it produced. Round-tripping the
+// candidate through a detached element puts both sides in the same normal form.
+let htmlNormalizer = null;
+function normalizedHtml(value) {
+ if (!hasDOM) return value;
+ if (!htmlNormalizer) htmlNormalizer = document.createElement('div');
+ htmlNormalizer.innerHTML = value;
+ return htmlNormalizer.innerHTML;
+}
+
export function applyCatalog(root, t) {
if (!root) return;
root.querySelectorAll?.('[data-i18n]').forEach((el) => {
@@ -119,6 +144,7 @@ export function applyCatalog(root, t) {
el.dataset.authNameOriginal = v;
if (el.dataset.authNamed === '1') return;
}
+ if (el.textContent === v) return;
el.textContent = v;
});
root.querySelectorAll?.('[data-i18n-html]').forEach((el) => {
@@ -132,7 +158,9 @@ export function applyCatalog(root, t) {
el.dataset.authNameOriginal = v;
if (el.dataset.authNamed === '1') return;
}
- el.innerHTML = v;
+ const normalized = normalizedHtml(v);
+ if (el.innerHTML === normalized) return;
+ el.innerHTML = normalized;
});
root.querySelectorAll?.('[data-i18n-attr]').forEach((el) => {
if (scriptOwns(el)) return;
@@ -141,8 +169,12 @@ export function applyCatalog(root, t) {
if (!attr || !key) continue;
const v = t(key);
if (v != null && v !== key) {
- el.setAttribute(attr, v);
- if (attr === 'data-i18n-title' || attr === 'title-text') document.title = v;
+ // Same identity guard as the two loops above. An attribute write is
+ // cheaper than a text-node swap, but it still produces a mutation
+ // record, and public/corner-stack.js re-measures the page's bottom
+ // chrome on every one of those.
+ if (el.getAttribute(attr) !== v) el.setAttribute(attr, v);
+ if ((attr === 'data-i18n-title' || attr === 'title-text') && document.title !== v) document.title = v;
}
}
});
diff --git a/tests/i18n-idempotent-writes.test.js b/tests/i18n-idempotent-writes.test.js
new file mode 100644
index 000000000..11b48ff18
--- /dev/null
+++ b/tests/i18n-idempotent-writes.test.js
@@ -0,0 +1,92 @@
+// @vitest-environment jsdom
+//
+// The catalog pass must not rewrite a node that already holds the catalog's
+// value. On the default locale that is nearly every node on the page: the markup
+// ships the English source and the English catalog hands the same string back.
+//
+// The cost is Largest Contentful Paint. Replacing an element's text destroys its
+// text node and creates a new one, and Chrome scores that as a fresh LCP
+// candidate at the moment it happens. The catalog lands after an async fetch, so
+// on a phone every page's LCP was re-dated to the i18n pass: measured on a Pixel
+// 5 over slow 4G against production on 2026-09-08, `/` reported LCP 10,188 ms on
+// `h1.hero-h`, a static heading, against an FCP of 2,336 ms.
+//
+// These tests pin the identity guard by node identity, not by value: the
+// assertion is that the ORIGINAL node survives, which is the only thing the
+// browser's LCP bookkeeping cares about.
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { applyCatalog } from '../src/i18n.js';
+
+// An "English catalog": every key resolves to the source text already in the DOM.
+const identity = (map) => (key) => (key in map ? map[key] : key);
+
+describe('applyCatalog leaves an already-correct node alone', () => {
+ beforeEach(() => {
+ document.body.innerHTML = '';
+ });
+
+ it('keeps the same text node when data-i18n resolves to what is there', () => {
+ document.body.innerHTML = '<p data-i18n="a.b">Already right.</p>';
+ const el = document.querySelector('p');
+ const before = el.firstChild;
+ applyCatalog(document, identity({ 'a.b': 'Already right.' }));
+ expect(el.firstChild).toBe(before);
+ expect(el.textContent).toBe('Already right.');
+ });
+
+ it('still replaces the text node when the translation differs', () => {
+ document.body.innerHTML = '<p data-i18n="a.b">Already right.</p>';
+ const el = document.querySelector('p');
+ const before = el.firstChild;
+ applyCatalog(document, identity({ 'a.b': 'Ya está bien.' }));
+ expect(el.firstChild).not.toBe(before);
+ expect(el.textContent).toBe('Ya está bien.');
+ });
+
+ it('keeps the same child nodes when data-i18n-html round-trips to what is there', () => {
+ // The raw catalog string is deliberately NOT byte-identical to the DOM's
+ // serialization (self-closing tag, single-quoted attribute). The guard has
+ // to normalize before comparing or it never matches and the whole fix is
+ // dead code that still looks present.
+ document.body.innerHTML = '<h1 data-i18n-html="h.1">The 3D agent<br>layer.</h1>';
+ const el = document.querySelector('h1');
+ const before = [...el.childNodes];
+ applyCatalog(document, identity({ 'h.1': "The 3D agent<br/>layer." }));
+ expect([...el.childNodes]).toEqual(before);
+ });
+
+ it('still replaces markup when the translation differs', () => {
+ document.body.innerHTML = '<h1 data-i18n-html="h.1">The 3D agent<br>layer.</h1>';
+ const el = document.querySelector('h1');
+ const before = el.firstChild;
+ applyCatalog(document, identity({ 'h.1': 'La capa<br/>de agentes 3D.' }));
+ expect(el.firstChild).not.toBe(before);
+ expect(el.textContent).toBe('La capade agentes 3D.');
+ });
+
+ it('does not re-set an attribute that already holds the catalog value', () => {
+ document.body.innerHTML =
+ '<img data-i18n-attr="alt:i.alt" alt="A 3D agent" src="/x.png" />';
+ const el = document.querySelector('img');
+ let writes = 0;
+ const observer = new MutationObserver((records) => {
+ writes += records.length;
+ });
+ observer.observe(el, { attributes: true });
+ applyCatalog(document, identity({ 'i.alt': 'A 3D agent' }));
+ // MutationObserver delivers asynchronously; a microtask is enough.
+ return Promise.resolve().then(() => {
+ observer.disconnect();
+ expect(writes).toBe(0);
+ expect(el.getAttribute('alt')).toBe('A 3D agent');
+ });
+ });
+
+ it('still writes an attribute whose translation differs', () => {
+ document.body.innerHTML =
+ '<img data-i18n-attr="alt:i.alt" alt="A 3D agent" src="/x.png" />';
+ applyCatalog(document, identity({ 'i.alt': 'Un agente 3D' }));
+ expect(document.querySelector('img').getAttribute('alt')).toBe('Un agente 3D');
+ });
+});