DEV Community: Melisa Wong

I diffed my Capacitor APK against my web build. 780 files inside it no longer existed.

Melisa Wong — Fri, 30 Oct 2026 14:04:53 +0000

I signed a release APK that was 585 MB. The web build it was supposed to contain is 182.7 MB. Compression does not explain a 3.5× gap, so I went looking — and what I found was worse than a size problem: 780 of the 1,397 files inside that APK no longer existed anywhere in my project.

Here is how the gap was made, how to spot it in about three seconds on your own app, and the guard script I now run before every signing.

The first guess was wrong in an instructive way

My instinct was "images are heavy". I listed the largest files inside the native project's copy of the web bundle:

ls -l android/app/src/main/assets/public/assets/*.js

69240126  Exploration-BM48lXvB.js
11977882  surname_info-BqOd4Hrh.js
  369001  index-DjfizeWu.js
  290721  pinyin_to_script-DzUio84d.js

A 69 MB chunk called Exploration. That is a real problem, but not the one I was hunting, because those filenames do not exist in dist/ at all. dist/assets/ contains exactly one JavaScript file:

83249461  dist/assets/index-RqoFan-G.js

Different build. Not "heavy images shipped next to the app" — a different bundle with a different code-splitting shape. The old one had a 369 KB entry plus a lazily loaded 69.2 MB chunk. The current one is a single 83.2 MB entry.

Diffing the two directories

Two sorted file lists and comm are enough to make the drift undeniable:

(cd dist && find . -type f | sort) > /tmp/web.txt
(cd android/app/src/main/assets/public && find . -type f | sort) > /tmp/native.txt

comm -23 /tmp/native.txt /tmp/web.txt | wc -l   # in the app, not in the build
comm -13 /tmp/native.txt /tmp/web.txt | wc -l   # in the build, not in the app

780   # in the app, not in the build
769   # in the build, not in the app

Out of 1,386 files in the build, only 617 were present in the app. Calling the rest "extra weight" is generous — the two directories were mostly unrelated.

The orphans accounted for 625.3 MB of 636.2 MB, i.e. 98.3% of the payload:

extension	files	size
`.jpg`	694	500.5 MB
`.js`	12	83.1 MB
`.png`	73	41.7 MB
`.css`	1	~0

Then the mapping became obvious. Every orphan had a same-named sibling in the new build with a different extension:

portraits/ — 292 .jpg → 292 .webp, identical basenames, identical subtrees
soul_trail/ — 379 .jpg → 379 .webp
calligraphy/ — 23 .jpg → 23 .webp
beasts/ — 73 .png → 73 .webp

The current dist/ has 767 .webp, 597 .svg, 18 .png, and zero .jpg. It is one image-format migration: JPEG/PNG → WebP. And it was a good migration — the 292 portraits alone went from 434.7 MB to 31.8 MB, same 292 images, 13.7× smaller.

So the real finding is not "my app is bloated". It is: I had already fixed the bloat, and the fix never reached the binary.

Why the APK still had the old files

Timestamps settle it:

app-release.apk                        Sep  8 19:49:19
android/app/src/main/assets/public     Sep  8 19:48:15
dist/                                  Sep 23 15:24:46

The native copy is 64 seconds older than the APK it produced, and 15 days older than the build it was supposed to represent.

This is not a Capacitor bug, and I checked the source instead of assuming. In @capacitor/cli 8.5.0, copyWebDir is:

await remove(nativeAbsDir);
return copy(webAbsDir, nativeAbsDir);

It wipes the destination and copies fresh. npx cap copy is a genuine sync, not a merge — so no stale-file accumulation is possible if you run it. The failure was mine: after the WebP migration I ran ./gradlew assembleRelease directly, because it is faster and because the app compiled. Gradle packaged whatever snapshot was sitting in assets/public, and nothing in the toolchain had an opinion about it.

That is the mental model worth internalizing. webDir: 'dist' does not create a link. It creates a copy, once, at the moment you invoke the command. After that, the native folder is a vendored dependency on your own past build — no version pin, no lockfile, no warning.

The three-second check

Hashed filenames are already a build fingerprint. You do not need a new tool to compare them:

unzip -p app-release.apk assets/public/index.html | grep -o '/assets/[^"]*'
grep -o '/assets/[^"]*' dist/index.html

in apk : /assets/index-ChvbOeYn.css  /assets/index-DjfizeWu.js
on disk: /assets/index-FYxpahNp.css  /assets/index-RqoFan-G.js

If those differ, the APK is not the app you have been testing in the browser. In my case it was not even close: I had been testing a single 83.2 MB entry bundle while signing a build that lazily loaded a 69.2 MB chunk. Same codebase, two different loading behaviours, and the one I validated was the one that never shipped.

Why this stays invisible for weeks

Stale builds do not crash. An old bundle is a valid bundle. The app launches, renders, and behaves like a slightly older version of itself.
Every local check reads the wrong directory. vite dev, vite preview, a browser tab — all of them read source or dist/. assets/public is only ever read by the packaged app.
Totals hide it; file lists don't. "636.2 MB vs 182.7 MB" reads as images are heavy. The correct reading was almost nothing in there is current.
Nobody diffs size between releases. Size is the one metric with no assertion attached to it, so it gets looked at only after someone complains about the download.

The guard

verify-web-assets.mjs — no dependencies, ~100 lines. It walks both directories into path → size maps, reports missing files, orphans (grouped by extension and summed), same-name-different-size files, and optionally pulls assets/public/index.html out of the APK to compare hashed asset references. Exit code 1 on any drift, so it can sit in front of assembleRelease.

Real output from my project:

web    1386 files, 182.7 MB
native 1397 files, 636.2 MB

MISSING in native: 769

ORPHANS in native: 780 files, 625.3 MB
  .jpg   500.5 MB
  .js     83.1 MB
  .png    41.7 MB
  .css     0.0 MB

APK CONTAINS A DIFFERENT BUILD
  in apk : index-ChvbOeYn.css, index-DjfizeWu.js
  on disk: index-FYxpahNp.css, index-RqoFan-G.js

RESULT: out of sync — run `npx cap copy` and rebuild.

The core is not clever:

const walk = (root, base = root, out = new Map()) => {
  for (const entry of readdirSync(root, { withFileTypes: true })) {
    const full = join(root, entry.name);
    if (entry.isDirectory()) walk(full, base, out);
    else if (entry.isFile()) out.set(relative(base, full), statSync(full).size);
  }
  return out;
};

const orphans = [...native.keys()].filter((k) => !web.has(k));

I also ran it against dist vs dist to be sure the "in sync" path is not a false-positive machine: 1386 / 1386, RESULT: in sync, exit 0. A guard that always fails is not a guard.

What I changed in the build process

The native folder is a build artifact, not source. Nothing in it deserves trust, including its timestamps.
cap copy and gradlew never get separated. One line, so half of it cannot be skipped: npx cap sync android && ./gradlew assembleRelease.
Fingerprint the artifact, not the folder. The index.html inside the APK is the cheapest proof of what was actually shipped.
Compare file lists before comparing totals. Totals produce a plausible story ("images") that can be completely wrong.
Gate the signing step. The check is a directory walk; it costs less than typing the keystore password.

None of this is Capacitor-specific in spirit. Any tool that vendors your web output into a native shell — Cordova, Electron, Tauri, a Docker image copied by hand into a server folder — has the same silent-drift failure mode: the copy is a snapshot, the snapshot has no version, and the build system will happily package a snapshot from last month.

The 585 MB APK was not a compression puzzle. It was a fifteen-day-old decision that nobody had re-run.

I build NameSoul, an app that gives you a Chinese name and the historical life behind it, in ten languages. It is one bundled web build inside a native shell, and it now gets diffed against itself before every signing.

My translation QA passed 31,020 strings. One locale had quietly lost 45% of its text.

Melisa Wong — Mon, 26 Oct 2026 17:45:08 +0000

I have a content corpus that people actually read: 282 story seeds, each with ten text slots, each slot translated into nine languages. One TypeScript file holds all of it. It is 56 MB.

Key parity passed. Placeholder integrity passed. Sentence-final punctuation passed. Then I grouped the same data by the batch that produced it, and one locale fell off a cliff.

This post is the four checks in the order I wrote them, why the first three could not possibly have caught the problem, and the one change to the translation pipeline that came out of it.

The corpus

The shape matters, so here it is exactly:

282 seeds (each one is a fixed piece of editorial content)
10 text slots per seed — two families of five variants each
11 locale fields per slot — the English source, the Chinese source, and nine translations
2,820 slots, 31,020 locale fields, 25,380 of them translated

Everything lives in one object keyed by seedId/family/variant. Translations arrived over about six weeks in batches — roughly one batch per content group — produced by a model, reviewed by me only by spot-reading. That last detail is the whole story.

Check 1 — key parity (necessary, and nearly useless)

The obvious first check: does every slot have every locale?

const LOCALES = ['es', 'ru', 'pt', 'fr', 'it', 'ar', 'de', 'hi', 'id'];

for (const [key, slot] of Object.entries(corpus)) {
  for (const loc of LOCALES) {
    if (typeof slot[loc] !== 'string' || !slot[loc].trim()) {
      missing.push(`${key} → ${loc}`);
    }
  }
}

Result: 0 missing across 25,380 translated fields.

That is a genuinely good result, and it told me almost nothing. A key-parity check answers one question — "did the write step crash?" — and it will happily pass on a string that says "Coming soon" in all nine languages. Presence is not correctness. I still run it first, because a null in the middle of a render is a crash rather than a quality problem, but I stopped treating a green result as a signal.

Check 2 — length ratio, and why the baseline has to be per locale

Translation length is not random. For prose against English, it is remarkably stable per target language. Median characters-of-translation ÷ characters-of-English, across 2,820 slots:

locale	median ratio	p01	p99
ar	0.822	0.65	1.93
ru	0.959	0.74	2.21
hi	0.967	0.77	2.16
es	1.060	0.84	2.40
pt	1.079	0.86	2.47
it	1.087	0.87	2.46
id	1.088	0.49	1.67
de	1.144	0.94	2.57
fr	1.174	0.92	2.74

Arabic at 0.82 and French at 1.17 is a 43% spread between two healthy locales. Any single global threshold — "flag anything under 60% of English" — is therefore wrong in one direction or the other for most of your languages. You have to calibrate per locale, then compare each string against its own language's baseline:

const median = arr => {
  const s = [...arr].sort((a, b) => a - b);
  return s[Math.floor((s.length - 1) / 2)];
};

const ratios = slots.map(s => s[loc].length / s.en.length);
const base = median(ratios);

const suspicious = slots.filter(
  s => s[loc].length / s.en.length < base * 0.6
);

Look at the id column above: p01 is 0.49 while its median is 1.088. That is not a tail, that is a second population hiding inside the distribution. I did not notice it at the time. Remember it for later.

Check 3 — sentence-final punctuation, and the 750 false alarms

If a translation is cut off mid-generation, it usually loses its final period. So: when the English ends with terminal punctuation and the translation does not, flag it.

I wrote the character class the way you write one when you are thinking in English:

const TERM = /[.!?。！？…؟।"'”’»)\]]\s*$/;

Run it and German explodes: 750 flagged strings out of 2,820.

My first reaction was that the German batch was badly broken. It was not. Every one of those 750 looked like this:

EN tail: ...you said: "Each of you. That was the plan."
DE tail: ...Du sagtest: „Jeder von euch. Das war der Plan.“

German typographic quotes are „…“ — they open with U+201E and close with U+201C, a character that is a left double quote everywhere else. My class had ” (U+201D) and ’ (U+2019) but not “ (U+201C), because in English “ only ever appears at the start of a quotation. So every German string that ended in dialogue ended in a character my regex considered non-terminal.

Add one code point and German goes from 750 → 5:

const TERM =
  /[.!?。！？…؟।"'”’»«“‹›)\]]\s*$/;

The lesson generalizes past German: your punctuation table is locale data, not a constant. French spaces its punctuation (« guillemets », ! with a preceding thin space). Arabic uses ؟ and ،. Hindi uses ।. Japanese and Chinese borrow full-width 。 and ！. A single flat class is a bug waiting to fire the first time a locale's typography disagrees with your assumptions — and it fires loudly, in the direction of false positives, which trains you to ignore the check entirely. That is worse than not having it.

After the fix, the real truncations were clean and obvious:

locale	truncated strings (of 2,820)
ru	30
pt	23
hi	19
fr	14
it	12
es	8
ar	6
de	5
id	3
total	120

120 out of 25,380 — 0.47%. Every one I opened was cut mid-clause, and the pattern was always the same: the model hit an output limit or a timeout, the client wrote whatever it had, and nothing downstream asked "does this sentence end?"

These are cheap to fix: re-request just the failing keys. 120 strings is one small batch.

Check 4 — the batch dimension, which is where it actually broke

id had the fewest truncations of any locale. Three. Its median length ratio was 1.088 — the healthiest-looking number in the table. Both of my checks agreed Indonesian was the best-translated language I had.

Then I did something I should have done on day one: I grouped the ratio by the batch that produced it, not by locale.

// batchOf(key) reads the content-group id off the seed
const byBatch = groupBy(slots, s => batchOf(s.id));

for (const [batch, group] of byBatch) {
  const base = median(group.map(s => s.en.length));
  const ratios = group.map(s => s[loc].length / s.en.length);
  report(batch, loc, median(ratios));
}

Per-locale median ratio, by batch:

content group	en avg chars	cn	es	de	id
group 1	1,095	0.31	1.09	1.18	1.13
group 2	1,328	0.27	1.04	1.12	1.12
group 3	1,290	0.28	1.05	1.14	1.12
group 4	1,388	0.27	1.00	1.10	1.11
group 5	1,290	0.28	1.01	1.14	1.10
group 6	1,593	0.29	1.07	1.12	1.12
group 7	945	0.28	1.04	1.11	1.11
group 8	1,096	0.30	1.10	1.18	1.11
group 9	1,170	0.31	1.16	1.22	1.02
group 10	1,262	0.31	1.18	1.23	0.99
group 11	1,518	0.30	1.06	1.14	0.64
group 12	1,741	0.28	1.04	1.12	0.57
group 13	1,226	0.30	1.08	1.16	1.09

Chinese, Spanish and German are flat across all thirteen groups. Indonesian drops to 0.64 in one group and 0.57 in the next, then returns to 1.09 — as if nothing happened.

202 strings, in two groups, roughly 45% shorter than their English source. And here is why check 3 missed them: 201 of the 202 end with a proper full stop. They are not truncated. They are condensed. The model summarised instead of translating, the output was well-formed, the writer step accepted it, and every structural check went green.

The damage is not a broken word at the end of a paragraph. It is a paragraph that no longer exists, in a language spoken by a few hundred million people, sitting in a shipped build for six weeks.

What changed in the pipeline

Four things, all cheap:

1. Verify at the write boundary, per key, with three assertions. Not "did the response parse" — that was already there — but: the key set returned equals the key set sent; the last character is terminal per a locale-aware class; the paragraph count matches the source's. A single number check would not have caught the condensing, and a single punctuation check would not have caught it either, but paragraph count diverges the moment a model drops a section.

2. Retry only the failures. 120 of 25,380 is 0.47%. Re-requesting those keys as one batch costs a fraction of regenerating a locale, and it keeps the keys that were already good — including the human-reviewed ones you do not want overwritten.

3. Store the baseline as a test fixture. The per-locale, per-batch median ratio is now a committed JSON file. Any future batch that lands more than ~25% off its locale's baseline fails CI before it reaches a build. This is a twelve-line test and it would have caught the Indonesian regression on the day it landed, not six weeks later.

4. Keep the batch id on the content, forever. This was the actual bug in my QA, not in my translations. A field that says which run produced a string costs nothing and lets you ask "was this one bad batch or a systemic decay?" — which is the difference between a targeted re-run and a two-week audit.

The general shape of the mistake

The three checks I wrote first all measured the artifact. Key present, ratio plausible, ends with a period. The failure was in the process that produced the artifact, and process failures are invisible unless the process leaves a trace you grouped by.

If I had to reduce this to one sentence: aggregate per-locale metrics are an average over your batches, and an average is exactly the thing that hides one batch going wrong.

I build NameSoul, an app that gives people a Chinese name and a story behind it — the corpus above is its content, in ten languages, and this is the audit that made me trust it.

I generated 87 pages from one template. Then I measured how similar they were.

Melisa Wong — Fri, 23 Oct 2026 17:09:12 +0000

Programmatic pages are easy to ship and hard to audit. You write one template, feed it a list, and get a directory of HTML files. Nothing errors. Every page renders. The nav works, the sitemap validates, and the whole thing looks finished.

The part that isn't finished is the part you can't see: how much of each page is actually about that page, and whether the machine-readable files describing your site agree with the files themselves.

I shipped 87 pages that way, then went back and measured them properly. Five of the numbers were not what I expected. Here they are, with the scripts that produced them.

The setup

One Node script, no framework, no bundler. Input is a JSON array of intents:

// intents.json
[
  { "slug": "michael-in-chinese", "family": "transliteration", "subject": "Michael" },
  { "slug": "chinese-names-that-mean-courage", "family": "meaning", "subject": "courage" }
]

Each entry becomes dist/<slug>/index.html. The renderer is a template literal that returns a string; the build writes it out. Across 87 pages: average 1,034 words of body text, roughly 18 KB of HTML per page, and zero <script src> on any content page — plain HTML with inline CSS, which is the one decision here I'd make again without hesitating.

Then I wrote a measurement pass that reads dist/ back and ignores the build's own bookkeeping. That distinction matters, and section 2 is why.

1. Similarity is a number. Measure it before you ship.

"Thin content" and "duplicate content" get argued about as vibes. They're measurable. Shingle the text at n=5 words and take the Jaccard index of every pair:

const shingles = (text, n = 5) => {
  const w = text.toLowerCase().split(/\s+/);
  const s = new Set();
  for (let i = 0; i + n <= w.length; i++) s.add(w.slice(i, i + n).join(' '));
  return s;
};

const jaccard = (A, B) => {
  const [small, large] = A.size < B.size ? [A, B] : [B, A];
  let inter = 0;
  for (const x of small) if (large.has(x)) inter++;
  return inter / (A.size + B.size - inter);
};

Results over all 3,741 pairs of 87 pages:

mean Jaccard 0.106
max 0.664
min 0.002
average 1,010 distinct 5-grams per page

A mean of 0.106 sounds great, and it is misleading. The site has three page families, and cross-family pairs sit near zero (the 0.002 minimum is a real pair that shares almost nothing), which drags the average down. The number that matters is within a family. Two adjacent transliteration pages score 0.462 against each other, and 59.6% of page A's 5-grams also appear in page B.

So two pages targeting genuinely different search intents are 60% the same text. That's the actual shape of the problem, and the site-wide average hid it completely.

The maximum pair was worth finding too: 0.664 between two privacy pages I wrote months apart and never diffed. Nobody would have caught that by reading.

What I changed: report similarity per family rather than per site, and fail the build if any intra-family pair exceeds 0.35. Getting under 0.35 forces each page to carry at least one block that is structurally impossible for a sibling to reuse — the actual transliteration table for that specific name, the actual character-by-character breakdown. Boilerplate paragraphs about "why Chinese names are meaningful" will never get you there.

2. Your sitemap is probably generated from the wrong source

Mine was built from intents.json — the list of pages I meant to publish. The site is built from dist/. Those two drift apart the moment a slug is renamed, a page is retired, or a tool page gets added by hand.

Measured drift:

directories in dist/: 92
<loc> entries in sitemap.xml: 87
directories absent from the sitemap: 5 (one interactive tool page, four asset directories)

None of that is fatal, but it's the wrong shape of truth. A sitemap claiming authority over a set of URLs it never looked at is a document written by hand pretending to be generated.

The fix is to derive it by walking the output directory and assert the counts match:

const urls = fs.readdirSync(DIST)
  .filter(d => fs.existsSync(path.join(DIST, d, 'index.html')));

Same bug class as a hand-maintained import list: any file that describes a set must be generated from that set, never alongside it.

3. `<lastmod>` was recording my build, not my edits

My sitemap stamped lastmod with the build date. Distribution across 87 URLs:

53 URLs: 2026-10-20
22 URLs: 2026-10-21
12 URLs: 2026-10-22
1 URL: 2026-10-13

Fifty-three different pages, all claiming to have changed on the same day. Most had not changed at all — the build simply re-ran after I edited a shared component. That's how you teach a crawler to ignore the field.

The fix is a content hash that outlives the process:

const hash = crypto.createHash('sha256')
  .update(renderedHtml).digest('hex').slice(0, 12);

const state = fs.existsSync(STATE)
  ? JSON.parse(fs.readFileSync(STATE, 'utf8')) : {};

state[slug] ??= {};
if (state[slug].hash !== hash) {
  state[slug].hash = hash;
  state[slug].lastmod = new Date().toISOString().slice(0, 10);
}

fs.writeFileSync(STATE, JSON.stringify(state, null, 2));

Now a rebuild that changes nothing produces a sitemap that changes nothing. That is the entire point of the field, and it requires state outside the build.

4. Title and description lengths are a distribution, not a setting

I checked one page's <title> while building it and it looked fine. Across all 87:

title length: avg 68, max 80, min 44 — 77 of 87 over 60 characters
meta description: avg 172, max 216 — 54 of 87 over 160 characters
85 of 87 titles end with the same | Brand suffix

The length problem is a template problem. One long h1 pattern plus one brand suffix fits the shortest page comfortably and overshoots the longest by twenty characters. There is no single value you can set; you have to check per page and let it fail.

The suffix problem is worse than the length problem. Ten characters of every title spent on a word nobody searches for, repeated across 85 pages, to reinforce a brand the domain name already states. It belongs on the homepage and nowhere else.

5. Don't generate the link graph from the template

Every page linked to the same 21 internal URLs. 87 pages × 21 identical links is very close to a complete graph — every page is equally important, which means none of them is.

Internal links are the one ranking-adjacent signal you fully control, and a uniform template throws it away. Rank candidates by data affinity — same family, shared subject, adjacent concept — then emit the top four to six. Two rules did most of the work:

never emit a link to a page in the same family that scores above the similarity threshold (you already decided those two are too alike to both deserve ranking)
never emit more than six; a link block that lists everything is navigation, not a recommendation

The guardrail: six assertions that fail the build

None of this is worth anything as a one-time cleanup. It has to be a verify.js that runs after the renderer and exits non-zero:

const checks = [
  ['sitemap count matches dist',   sitemapUrls === distDirs],
  ['no orphan directories',        orphans.length === 0],
  ['no bulk lastmod stamping',     maxPerDate <= 5],
  ['titles <= 60 chars',           titles.every(t => t.length <= 60)],
  ['descriptions <= 160 chars',    descs.every(d => d.length <= 160)],
  ['intra-family jaccard <= 0.35', worstPair.jaccard <= 0.35],
];

All six failed on the first run. Three passed by the second. The similarity assertion took real work, because the only way under the threshold is to give every page content that comes from data specific to it.

The general lesson is the one I keep re-learning: programmatic pages don't fail loudly. No exception, no red build step, no 404. You get 87 files that render, a sitemap that validates, and then the slow realisation that the site is one page printed 87 times with a noun swapped. The only way to know which of those you built is to measure the output instead of the input.

I build NameSoul — the site above is what it looks like when a very small team generates its content instead of writing it.

A Chinese Name Is Two Records That Never Meet

Melisa Wong — Wed, 21 Oct 2026 12:15:29 +0000

A naming app looks like a string generator from the outside. You put in a surname, a gender, a style and a date, and two characters come out.

Generating the characters is the least interesting thing in NameSoul. What took the time is the two records that hang off the name, and the fact that they are keyed by different things and never joined to each other.

(Ep.4 of a short series about building this.)

Inputs, outputs, and what the name actually is

Input: a surname, a gender, a style, a date of birth.

Output, in the order the user meets it: a given name; a historical figure who shares the surname; a past-life figure matched to the name's temperament; the places tied to that figure; then six small artifacts, which are a voice clip, the bilingual text, the surname in seal script, the full name in brush, a colour derived from the birth date, and a personal seal.

The name is the index. Everything else is a lookup through it.

That is the whole architecture, and it is deliberately shallow. There is no model deciding anything at runtime. The decisions were made before the app existed, one record at a time, and the app just walks the path.

Record A is keyed by surname

The first record is "who carried this surname."

Pick Li. Under the name, one line appears: this name shares a lineage with Li Bai. Then a few lines about him, and one moment from his life where he was most himself.

The key here is the surname and nothing else. It does not care about the given name, the style, or the birth date. If two users with different given names both pick Li, they get the same Record A. That is intentional.

Why key it on the surname? Because the surname is the part of a Chinese name nobody chooses. It arrives with you. If a name is going to have roots, the surname is where they are. So this lookup answers one question only: who stood behind this character before you did.

Record B is keyed by temperament

The second record is "whose nature does this name carry."

This one is not keyed on the surname. It is keyed on the given name's meaning, imagery, and feel. The figure who comes back may share nothing with you. Different surname, different era, different life. What matches is the quality the name points at.

Two different keys, two different questions. A gives you a lineage. B gives you a direction. One looks back, one looks forward, and they never need to agree.

Why not merge them into one record

Merging is the obvious simplification, and it breaks the product in a specific way. If one person had to satisfy both conditions, the pool would collapse to "famous people whose surname also happens to fit this name's temperament." You would see the same handful of names repeatedly, and the second half of the app would become a lookup table of four people.

Keeping them separate costs one join that never happens and buys a much larger pool on each side. That trade was easy.

The selection problem was harder than the writing

I assumed writing would be the bottleneck. It wasn't. Choosing was.

Chinese history has more named figures with real personalities and documented lives than anyone can hold. Including all of them is impossible and would also be worse. So the filter came down to three rules:

Famous first. Household names in China, at least recognizable abroad. They act as entry points, because recognition is what makes a user keep reading.
Then the ones nobody outside China knows, whose lives are still extraordinary. Some are not even well known inside China. The interesting part of a culture usually lives here.
Temperament has to match. This was the hard filter, and the one I refused to bend. You cannot take a famous person and attach them to a name because the name is popular. Something in that person has to actually answer the name.

After selecting, there is still the research: collected works, historical records, biographies, hunting for the one vivid fragment. Where was he standing. What did he say. Which poem. Which choice.

The honest limit

I can't exhaust Chinese history, and I'm not going to pretend the coverage is complete. What I do is select and match, and keep every entry sourced rather than invented. The standard I hold is "this figure is real, this moment is documented, this quality is his." The standard I can't promise is "nothing important is missing."

Places are a third lookup

The places hang off Record B, not off the name: cities he lived in, mountains and rivers he crossed, what he left behind, where he was buried.

I added them because a name that ends at a person is a fact, and a name that ends at a landscape is a reason. From a name to a person to a city to a place you could stand in. That last step is the only one I actually care about.

What the split bought

One record would have been simpler to build and much worse to use. Two records means the name can be new every time while the historical layer stays honest, and it means the same user can come back, change the style, get a different name, and land on a completely different person without the surname record being disturbed.

The whole app is this: a short path through records that were chosen slowly.

One question

If you were building this, what would you key Record B on? Temperament is the answer I landed on, and it is the least defensible one on paper, because "temperament" is not a field you can query.

I'd genuinely like to hear how someone else would model it. I made NameSoul, it's at namesoul.net, and the parts I'm least sure about are exactly the parts I'd most like argued with.

The 83 MB JavaScript bundle was not a dependency problem

Melisa Wong — Mon, 19 Oct 2026 14:04:43 +0000

I ran ls -lh on a production build last week and got this:

-rw-r--r--  1 user  staff   3.8K  index-FYxpahNp.css
-rw-r--r--  1 user  staff    79M  index-RqoFan-G.js

Seventy-nine megabytes of JavaScript. One file. One line, 13,308,122 characters long.

The stylesheet, for comparison, is 3.8 KB. The CSS is a rounding error next to the script.

This is a React app packaged with Capacitor, so there is no CDN and no lazy route to hide behind. That 79 MB file is inside the app binary, read from local storage on every cold start, and parsed before the first screen paints.

This post is the audit I should have run two months earlier, the three reasons the usual tooling missed it, and the split that brought the entry chunk down to something reasonable.

How a bundle gets to 79 MB without anyone noticing

Nobody adds 79 MB of JavaScript on purpose. You add a data file.

This app is a content product. Every record it ships carries two text sections — one shown under the main illustration, one in a separate panel — and each section exists in several variants so a user does not see the same paragraph twice. Every string is localized into ten languages, with the source text kept alongside.

Text meant to be read is not redundant, so it compounds fast. A few hundred records multiplied across sections, variants, and languages is already tens of thousands of strings — and all of it was living in a source module.

The data lived in a module like this:

// content.ts
const db: ContentDB = {};

db["group-male-01"] = {
  sectionA: { A: { en: "...", es: "...", /* more */ }, B: { /* ... */ }, /* more variants */ },
  sectionB: { A: { /* ... */ }, /* ... */ },
};

db["group-male-02"] = { /* ... */ };
// ... hundreds more assignments
export default db;

And it was imported the normal way:

import db from './data/content';

That is the whole story. A single TypeScript data file that had grown well past 50 MB became a 79 MB minified chunk, and the build reported success.

Two details matter more than they look:

It is an imperative build, not a literal. db[key] = {...} is a side effect. Bundlers cannot tree-shake it, cannot see the shape of the object, and cannot split it. You get one evaluation unit, all or nothing.

It is imported by the entry module. Even if the data were a plain object literal, a static import from main.tsx puts it in whatever chunk main.tsx lives in. In this build there is exactly one JS file, so "the entry chunk" and "all of the app's content" are the same artifact.

Why the bundle analyzer was quiet

I ran the analyzer. It showed a clean report: React, React DOM, a router, a state library, a date library. Nothing over 200 KB. Total dependency weight looked perfectly healthy.

The analyzer was not lying. It lists packages. My weight was in ./src/data, which is my own code, and own code does not get a row unless it is a big named import. The tool answered the question I asked ("which packages are heavy?") instead of the question I had ("which bytes are large?").

Three checks would have caught it in seconds, and none of them are on by default:

# 1. raw size of every emitted chunk, sorted
ls -lS dist/assets/*.js | head

# 2. gzip size, because raw size alone scares people about the wrong things
for f in dist/assets/*.js; do
  printf "%8s raw  %8s gz  %s\n" \
    "$(wc -c < "$f")" "$(gzip -9 -c "$f" | wc -c)" "$f"
done

# 3. the tell: a single line longer than 100 KB is inlined data, not logic
awk '{ if (length($0) > 100000) print FILENAME": line "NR" = "length($0)" chars" }' dist/assets/*.js

The third one is the one I now trust most. Minified code is long-lined but bounded. A minified data literal produces one absurd line, and in this build that line is 13.3 MB. If you see that, stop looking at your dependencies.

Gzip does not rescue you

Compressed, the chunk goes from 83,249,461 bytes to 31,707,388 — a 2.62× reduction. That is worse than typical for code (usually 3–4×), because prose in ten languages is not as redundant as machine-generated identifiers.

So even after compression: 30 MB. And compression only helps the transfer, not the parse. The engine still has to parse and evaluate 83 MB of source on the device. Parse-only cost on my laptop, measured with node --check (no execution, no React, no rendering):

real 2.80
real 1.92
real 1.47

Call it 1.5–2.8 seconds, before any of my code runs, on an M-series Mac. A mid-range Android phone is not faster at this than a laptop. That is the entire cold-start budget spent on reading paragraphs that the user will not see for another four taps.

Why this is specifically worse inside a packaged app

On the web, this is a bad first-load story. In a Capacitor build it is three separate problems:

Install size. With images and fonts included, what ships on disk is roughly twice the size of that script alone. All of it is copied into the binary. Store listing pages show that number to users before they have seen a single screen.

No delivery tricks. No CDN, no HTTP caching between releases, no range requests, no "load the rest later" over the network. The WebView reads the file from disk. Every improvement has to happen at build time.

Updates are whole. A fix to one typo in one paragraph can produce a new binary, because the paragraph is compiled into the bundle. There is no such thing as a small content patch.

On the web you would split the route and ship a spinner. In a packaged app the same weight shows up as install friction and cold start, and no RUM dashboard will page you about it.

The split

I did not shrink the content. Truncating a content product to hit a byte budget is solving the wrong problem. I moved the content out of the parse path.

The key detail is that the record keys are already hierarchical — group-male-01, group-female-03 — so the first segment is a natural partition. Instead of one module that contains everything, the build now emits one JSON file per group and a small manifest:

public/content/manifest.json      # { "<group>": <count>, ... }
public/content/<group>.json       # records for that group
...

The loader is about thirty lines and does not need a framework:

type Manifest = Record<string, number>;
let manifest: Manifest | null = null;

export async function loadGroup(id: string): Promise<Record<string, unknown>> {
  manifest ??= await fetch('/content/manifest.json').then(r => r.json());
  if (!(id in manifest)) throw new Error(`unknown group: ${id}`);

  const res = await fetch(`/content/${id}.json`);
  if (!res.ok) throw new Error(`content ${id}: ${res.status}`);
  // JSON.parse beats JS parse per byte, and it cannot execute anything
  return res.json();
}

Three things made this work in practice:

fetch on a local origin works in the WebView. A bundled Capacitor app still serves capacitor://localhost (or http://localhost on Android) through its internal scheme handler. Relative fetch to a file inside dist/ behaves like a normal static request.
JSON.parse is cheaper than executing a JS object literal. Both are linear in bytes, but the JSON parser does not build a scope, does not evaluate expressions, and can bail out on malformed input instead of running it. For pure data, JSON is the right container.
The variant split happens after load, not before. All variants come down with the record. Splitting to one variant per request would have cut bytes on paper and tripled the request count for a user who swipes through the gallery — the wrong trade on a device where every request costs a tick.

The entry chunk now carries routing, state, and UI. Content arrives per group, and the first screen requests one file for the one group it is showing.

The budget check I keep in CI

The rule I settled on is boring and has caught two regressions since:

// scripts/budget.mjs — runs after build, exits non-zero on breach
import { readdirSync, statSync, readFileSync } from 'node:fs';

const dir = 'dist/assets';
const CHUNK_LIMIT = 2 * 1024 * 1024;   // 2 MB per chunk, raw
const LINE_LIMIT  = 100 * 1024;        // 100 KB in one line = inlined data

let failed = false;
for (const file of readdirSync(dir).filter(f => f.endsWith('.js'))) {
  const path = `${dir}/${file}`;
  const size = statSync(path).size;
  if (size > CHUNK_LIMIT) {
    console.error(`chunk over budget: ${file} = ${size} bytes`);
    failed = true;
  }
  const longest = readFileSync(path, 'utf8').split('\n')
    .reduce((max, line) => Math.max(max, line.length), 0);
  if (longest > LINE_LIMIT) {
    console.error(`inlined data suspected: ${file} longest line = ${longest}`);
    failed = true;
  }
}
process.exit(failed ? 1 : 0);

The line-length check is a heuristic, and I know it. It is also the only check in the file that ever predicted a real problem before a human noticed.

What I would tell someone packaging a content app

Measure the artifact, not the dependency tree. The analyzer answers "which packages are heavy". Data you authored is invisible to it, and data you authored is usually the weight.
Keep content out of the parse path from day one. Not "we will split it later" — later means after the prose has grown past 50 MB and every key is already compiled in.
Treat a long single line as a bug signal in review. It costs one awk and it is unambiguous.
Compression is a transfer story, not a runtime story. 2.62× smaller on the wire; the same bytes to parse.

None of this is exotic. It is the ordinary consequence of a content product whose content was stored where code goes.

I build NameSoul, an app that gives people a Chinese name along with the historical story behind it — a content-heavy product in ten languages, and, for a while, one very large JavaScript file. If you are shipping a text-heavy app through Capacitor, the numbers above are yours to reuse: namesoul.net.

My i18n function takes eleven positional arguments. Here is what that cost me.

Melisa Wong — Wed, 14 Oct 2026 14:38:24 +0000

Let me start with the real signature, because it explains everything that follows.

export function mainText(
  lang: AppLanguage,
  en: string,
  esText?: string,
  ruText?: string,
  ptText?: string,
  frText?: string,
  itText?: string,
  arText?: string,
  deText?: string,
  hiText?: string,
  idText?: string,
): string {
  if (lang === 'es' && esText) return esText;
  if (lang === 'ru' && ruText) return ruText;
  if (lang === 'pt' && ptText) return ptText;
  if (lang === 'fr' && frText) return frText;
  if (lang === 'it' && itText) return itText;
  if (lang === 'ar' && arText) return arText;
  if (lang === 'de' && deText) return deText;
  if (lang === 'hi' && hiText) return hiText;
  if (lang === 'id' && idText) return idText;
  return en;
}

Eleven positional arguments. One if per language. English as the fallback. No keys, no lookup table, no t('some.nested.key').

This is the entire UI translation layer of an app that ships in ten languages, and it is called roughly 150 times.

I wrote it, and it works. But I want to walk through what it cost me, because the cost is not where you would expect it to be.

Why I wrote it this way

I want to be fair to the original decision, because it was not careless. It was a trade I made on purpose.

The alternative is the standard key-based API:

t('createName.firstName') // → 'Nombre / 名'

For this project, the problem with that was friction at the call site. When I write UI, I want to see the actual string I am rendering. With mainText(...) I get the English, the Spanish, the Arabic — all of it — right there in the JSX. I never have to open a second file to know what the user reads. And when I add a language, TypeScript hands me a signature that lists every slot, so the editor tells me what to fill in.

For a solo project with a fixed set of languages, that is genuinely pleasant. It is a local-optimization win.

It is also a trap. Here is why.

Cost 1 — parameter order becomes an invisible contract

Read the order again: en, es, ru, pt, fr, it, ar, de, hi, id.

That is not alphabetical. I ordered them by when I happened to write them, which is exactly the kind of ordering that feels obvious to the person who chose it and is invisible to everyone else — including me, three months later.

Now look at a real call site:

title={mainText(language, 'Listen', 'Escuchar', 'Слушать', 'Ouvir', 'Écouter', 'Ascolta', 'استمع', 'Hören', 'सुनें', 'Dengar')}

Ask yourself: if you were writing this line late at night, which slot would you get wrong?

Nothing enforces the order. Every argument is a string | undefined. If you swap the Portuguese and Russian slots, TypeScript is completely happy. You ship a Russian string to Portuguese users, the build passes, and the only thing that catches it is a human reading the Portuguese UI.

That is the worst class of bug: it type-checks, and it is silent.

Cost 2 — a missing argument fails silently, in English

Look at the fallback again:

if (lang === 'es' && esText) return esText;
// ...
return en;

Two conditions must both hold: the language matches, and the string is present. Forget to pass the Spanish string, and esText is undefined, the condition fails, and the function returns English.

Nothing throws. Nothing logs. The Spanish user simply sees one English button in an otherwise Spanish screen.

With ten languages and ~150 call sites, that is not hypothetical — it is a matter of time. And because English is a legitimate, expected outcome, you cannot flag it at runtime without drowning in noise.

The fix is boring, and it took me too long to apply: make the arguments required instead of optional, and add a dev-only assertion that every language has a value. Optional parameters trade compile-time safety for call-site convenience, and in an i18n layer that is the wrong trade.

Cost 3 — the source language is not a language

This one is the most interesting, and it is specific to how this product works.

Every screen shows the target language on the main line and Chinese underneath it, always. Not behind a toggle. Not as a second language pack. Chinese is rendered alongside every other language because it is the content — the thing being translated, shown in parallel.

So the language packs do not look like this:

firstName: 'Nombre',

They look like this:

firstName: 'Nombre / 名',
gender: 'Género / 性别',

The Chinese is welded directly into each of the nine packs. One field renders the whole bilingual line, so the UI code stays trivial.

That has a consequence I got wrong for a while: the app has no Chinese interface, and it never should. Chinese is not the eleventh language — it is the source that all ten languages are stacked on top of. For a while the type union still allowed 'zh', and a test build that injected ns_lang=zh would drop the user into a "pure Chinese interface" that did not actually exist. A ghost locale. I sealed it by removing zh from every runtime whitelist — detection, persistence, selector — while keeping the type honest.

The lesson generalizes: decide whether your source language is a language or an input. If it is an input, it must not be selectable. Leave it selectable "just in case", and you will eventually ship a fake locale.

Cost 4 — RTL is not `dir="rtl"`

Arabic is in the set, so there is one line that flips the document:

useEffect(() => {
  const isRTL = language === 'ar';
  document.documentElement.lang = language;
  document.documentElement.dir = isRTL ? 'rtl' : 'ltr';
}, [language]);

That handles maybe 80% of it. The remaining 20% is where the bugs live:

Mixed-direction lines. A badge showing a Latin-script name next to Chinese characters does not simply mirror — the runs reorder and the punctuation lands on the wrong side. That needed explicit LTR isolation on the badge itself, not on the page.
The Chinese helper line. The Chinese sub-line should still read left-to-right inside an RTL page. Let it inherit rtl and the punctuation jumps to the start of the line.
Numbers and Latin text inside Arabic sentences. Fine at the document level, broken the moment they sit next to a bracket or a slash.

The systematic fix is logical CSS properties: margin-inline-start instead of margin-left, padding-inline instead of padding-left, text-align: start instead of left. Every physical property you write is a future RTL bug you have not found yet.

Cost 5 — machine translation hides its own failures

The languages beyond English and Chinese came from batched machine translation. Two things I learned the hard way.

Truncation looks like a short translation. Some model responses quietly summarize long paragraphs instead of translating them. There is no error — you get a shorter, plausible string. The cheapest detector is a ratio check: flag any translated field whose length falls below ~30% or above ~300% of the source. That one heuristic caught most of my bad fields.

Batch size is a reliability knob, not a speed knob. Bigger batches finish faster and fail more often, with empty responses under rate limiting. Small batches with a resumable log — key, source, translation, model, request id — let me rerun only what failed and never silently drop a field.

What I would do instead

If I were starting over, the checklist is short:

One exported array of language codes is the single source of truth. The type, the detector, the whitelist and any iteration all derive from it, so adding a language touches one place.
Translation values live in an object keyed by language code, not in positional slots. A missing language becomes a type error instead of a silent English fallback.
Required, not optional. If a language must have a value, say so in the type.
Logical CSS properties from day one — RTL is a writing mode, not a stylesheet rewrite.
The source language is an input, never a selectable locale.
Machine translation ships with an audit log and a length-ratio sanity check.

The positional signature still works, and at 150 call sites the cost of rewriting it has not yet beaten the cost of leaving it. But it is the one decision in this codebase I would take back first.

I build NameSoul, a Chinese naming app that currently runs in ten languages. The i18n layer above is the part of it I still think about the most.

I don't know how to code — I shipped a 10-language app anyway. Here are the 6 decisions.

Melisa Wong — Mon, 12 Oct 2026 18:25:13 +0000

I'm going to skip the inspiration and give you the engineering decisions, because that's what I'd want to read.

Context: I'm a solo developer with no technical background. I built NameSoul, an app that generates a Chinese name for a non-Chinese speaker and then treats that name as a starting point — six style paths, a real historical figure behind each name, seal-script and calligraphy rendering, audio on every name, ten languages. No team, no funding, no prior code.

Here are the six decisions that actually determined the outcome.

1. Architecture before features

The first thing I did wasn't writing features. It was mapping the framework: where users enter, what they see first, what they do second, how a name gets generated, what gets displayed afterwards, how the pages connect.

I drew it out on paper, repeatedly, before letting AI turn any of it into something executable. Skeleton first, flesh second. If you start from features, you end up refactoring your data model three times.

2. Learn to talk to AI before you learn to code

My earlier projects all failed, and one big reason was the tooling: AI couldn't follow what I actually meant. I'd say A, it would give me B; I'd explain for ages and it would produce an even more absurd C.

What changed wasn't the models getting smarter. It's that I learned to decompose. Small, unambiguous, verifiable steps. Describe the interface as a contract, not a vibe. The bottleneck was never my typing speed — it was the specificity of my instructions.

3. Treat aesthetics as a separate discipline

AI is genuinely good at logic and structure. It is close to useless at visual design. What it produced was functionally correct and visually wrong in a way that's hard to articulate — nothing obviously broken, but something off.

What worked: referencing. I screenshotted sites whose feel matched what I wanted and said "this direction, this density, this restraint." Concrete references outperform adjectives by an enormous margin.

I also deliberately cut animations and motion polish I couldn't land well. Shipping something solid beat shipping something half-animated.

4. Data is a product decision, not a content task

The single most expensive part of this build was not code. It was building a vetted dataset of historical figures, with accurate, English-friendly notes, verified against real geography — cities, landscapes, historical sites.

Generated bios read smoothly and mean nothing. A curated dataset is dramatically slower, which is exactly why most tools skip it. That asymmetry is the product.

5. Localization is content, not just strings

Ten languages, and the hard part isn't the UI. Every name explanation and every story has to be translated properly — accurate, natural, with some warmth — then proofread, then checked for layout breakage in that language.

If you've only ever localized a UI, multiplying that by full content is a different order of magnitude. Plan for it before launch, not after.

6. Refuse the lazy version, but know which laziness is fatal

Standard advice: ship the crudest usable version, validate demand, then build.

I only took half of it. Demand validation — sure, but the market already proves the category has demand. The crude-shipping half I rejected, because I'm a user too, and I wouldn't download a version I'd be embarrassed to recommend.

That said, I did cut scope aggressively elsewhere. "Refuse the lazy version" isn't "build everything" — it's choosing the two or three places where shortcuts would hollow out the product, and taking the shortcut everywhere else.

What I'd tell the next person

The architecture diagram is not overhead. It's the thing that keeps you from rewriting yourself into a corner.
Your prompt quality is your engineering skill right now. Decompose, constrain, verify.
For visual work, collect references before you ask for anything.
Budget your time for data and localization. That's where the product actually lives.

The app is live. I'm now going back through it for v1.1 and I'd rather hear what's broken than what's fine.

Source / product: namesoul.net

From a name to a habit: the 6 product layers behind NameSoul (and what I cut)

Melisa Wong — Sun, 11 Oct 2026 14:51:53 +0000

I build a Chinese naming app called NameSoul. The interesting part, for this community, isn't the naming — it's that the product is deliberately layered, and every layer exists because the layer below it failed on its own.

Here's the design, and the things I tore up on the way.

The premise

People search "give me a Chinese name." Every existing tool answers the same way: input English name → output Chinese name → done. One use. No reason to return.

I read that as a product smell. A one-shot tool has no retention surface. So the question became: what if the name is not the output, but the input to a longer path?

The six layers

Layer 1 — Choice with personality

Six stylistic paths: bold (豪放), poetic (诗意), Five Elements (五行), nature (自然), homophonic (谐音), rustic (田园). These are not cosmetic filters — each path is a different temperament, so the name itself is structurally different. Every result ships with a written rationale: character choice, cultural context, and how tone, form and imagery work together.

Layer 2 — Grounding in real people

Each name maps to a real historical figure. This is a data problem, not a copywriting problem: a curated set with accurate, English-friendly explanations. No invented characters, no vague "ancient scholar" stand-ins.

Layer 3 — Making the abstract visible

Enter a surname and it renders in seal script as a calligraphic "totem," plus brush calligraphy for the name itself. This is the layer where users go "I had no idea writing could look like this."

Layer 4 — Time as a coordinate

Birth date produces a lucky color and a personal seal. The framing matters here: it is a personal coordinate, not a prediction. That distinction drove more copy edits than any feature.

Layer 5 — Story as the payload

The "past life in China": figure, era, cities, landscapes. The design intent is that a user leaves curious about a place, not just a word.

Layer 6 — The retention hook

A daily "shake the stick" — one line, one day. Cheap to build, and it converts a one-time event into a daily habit.

Two implementation details worth stealing

Voice clip on every name. Foreigners can't read Chinese, and a name you can't pronounce is a name you can't own. Native audio was a small feature and it's the one users mention most.
Bilingual everywhere, not just on the result screen. An American sees English + Chinese; a French user sees French + Chinese. Chinese isn't the result — it's the environment.

What I cut

The first version leaned much harder on a "fate" framing — fortune-style language that demoed well and felt wrong in product. It flattens a culture into a horoscope. I removed it and rebuilt the copy around history, geography and aesthetics instead. Slower to write, and far more honest.

Where it is now

10 languages · 6 styles · real historical figures · 73 guardian beasts · audio on every name.

I'll write the technical side: how the seal-script rendering, the multi-language content pipeline, and the audio actually work — including the parts I'd do differently.

Live app / source of the content: namesoul.net