Converting Unicode Text to Decimal HTML Entities With a Client-Side Tool

What a decimal entity actually encodes

An HTML entity is not a picture of a character. It is a number, and the number is the character's Unicode code point expressed in base ten. The pattern is an ampersand, a hash mark, the decimal number, and a semicolon — nothing else:

Because the number is the code point, the entity survives any transport that mangles raw bytes. A UTF-8 encoded e-acute is two bytes; an em dash is three; a Chinese character is three; the grinning emoji is four. Decimal entities are always ASCII, so a gateway that strips high bytes, a mail relay that re-encodes text, or a legacy XML parser with an unexpected charset has nothing left to corrupt. That is the entire mechanism, and it is why entity conversion is described as an encoding fix rather than a font fix.

Three styles, three different outputs

A client-side entity tool normally exposes named, decimal and hexadecimal output, and the three are not interchangeable in the way the labels suggest.

Named output uses the short mnemonic forms for the characters that have them: & for an ampersand, < for a less-than sign, > for a greater-than sign and " for a double quote. Those four are the whole built-in table. Everything else that needs escaping has to fall back, and the fallback in most tools is hexadecimal rather than a name — so "named" mode on a euro sign produces €, not €. Reading the output is the only reliable way to know which form a given tool actually emitted.

Decimal output produces the uniform é shape and never leaves a character half-converted.

Hexadecimal output produces é with an upper-case digit run. Both numeric forms render identically in every modern browser, so the choice is about the consumer of the string, not about the browser.

The output width differs as well, and the difference compounds. A decimal entity is six characters long for a two-digit code point and eight for a four-digit one; a named entity such as é is eight; a hex entity is six. Converting 1,500 accented characters therefore turns 3,000 bytes of UTF-8 into roughly 9,000 bytes of decimal-encoded ASCII, and 12,000 bytes if every character gets a named form. Budget for that when the payload travels through a size-limited channel.

The apostrophe trap, and why ' is not ’

Most entity converters emit ' for an apostrophe, because HTML 4 never defined a named entity for it and ' is an XML addition that older HTML parsers do not recognize. That is the straight, typewriter apostrophe.

Typographic text rarely contains it. Word processors and content management systems submit U+2019, the right single quotation mark, which is ’. The same split applies to quotation marks: " is the straight double quote and “ and ” are the curly pair.

This matters because the two are not the same character and no decoder will swap one for the other. A string encoded with ’ and decoded as ' round-trips to a different text, and an application that compares a pasted apostrophe against a stored one will fail. When a round-trip test produces text that looks identical on screen but fails a string comparison, check the apostrophe and the dash before anything else.

Astral characters: one code point, two UTF-16 units

Unicode 15.1 defines 149,813 assigned characters, and the range runs past the 65,535th code point. Everything above U+FFFF — most emoji, some rare scripts, mathematical alphabets — cannot be written as a single UTF-16 unit, so a naive encoder that iterates over UTF-16 units rather than code points will split the character and emit two surrogate entities such as ��, which no browser will reassemble into an emoji.

The correct output is a single entity for the whole code point: the grinning face is U+1F600, so it encodes to 😀 in decimal or 😀 in hex. When a converted string produces two adjacent entities in the D800-DFFF range, the converter is walking UTF-16 units and is the wrong tool for anything outside the basic multilingual plane.

Auto-detect and the double-encoding trap

Direction detection is a heuristic, and a typical implementation compares the number of entity tokens it can find against the number of raw ampersands, angle brackets and comparison signs left over after those tokens are removed. If entities outnumber the residue, the input is treated as already encoded and is decoded; otherwise it is treated as plain text and encoded.

The heuristic is sound, and it still needs a check on the output, because decoding must happen exactly once. Consider the string A: the first token is the hexadecimal form of the ampersand itself. Decode it and the result is A, still an entity, which the browser will then render as the letter A. A decoder that runs its hexadecimal pass and then its decimal pass over the same output — the classic three-pass implementation — collapses both levels in one call and returns a bare A. That is a silent data change, and it is invisible until someone compares the round-tripped string against the original. The safe rule is one pass, left to right, with no rescanning of substituted text.

When decimal entities are the right answer

They are the right answer when the receiving system is unknown or old: HTML email templates, RSS items, XML feeds, SMS gateways, syndication partners and CMS imports all belong on that list. Converting to numeric entities makes the payload pure ASCII, which removes charset negotiation from the failure surface entirely.

They are the wrong answer inside a JSON API, where the escape sequence \u00e9 is the native form and entities arrive as literal text. They are wrong in a database column, where storage encoding solves the problem properly. They are also unnecessary in modern HTML served with an explicit UTF-8 declaration — but harmless, which is why the conservative habit persists.

A four-point check before you ship the string

• Confirm the style you selected is the style you got: named mode may be emitting hex for anything without a mnemonic.
• Confirm Non-ASCII conversion is switched on. Without it, the ampersand, angle brackets and quotes are escaped and every accented letter is left alone.
• Round-trip the result back through the decoder and compare character by character, not visually.
• Watch for paired surrogate entities when the text contains emoji, which indicate the converter is iterating UTF-16 units instead of code points.

The whole operation runs in the browser, so nothing is uploaded and the page keeps working after the network is disconnected — which is the practical reason a client-side converter is preferred over pasting proprietary template text into a hosted service.