ZPL Unicode Printing: A Practical UTF-8 Checklist

Few things are more irritating than a label that says “Café” when it should say “Café”. The label looks fine in your editor, the data looks fine in the database, and yet something between the two has mangled it. The good news is that this problem has a short list of causes, and you can work through them in order.

1. Tell the printer to expect UTF-8

By default the printer reads your text with an older single-byte character set. To switch to UTF-8, put ^CI28 near the top of the label:

^XA
^CI28
^FO40,40^A0N,40,40^FDCafé, Zürich, São Paulo^FS
^XZ

If you’ve done this and the problem remains, don’t stop here. This step is necessary but rarely sufficient. And if your data isn’t UTF-8 at all, using ^CI28 will make things worse. The setting has to match what you send. The full list of values is in Unicode and code pages.

2. Find out what encoding the file really has

Open the file in an editor that tells you its encoding. Some editors and some older programs save files as Windows-1252 or “ANSI” without making a fuss. If the file is in one of those and you’ve told the printer UTF-8, the accents will break. Either convert the file to UTF-8 or set the printer to the matching code page.

3. Watch for the byte-order mark

A byte-order mark, or BOM, is three invisible bytes some programs add at the very start of a UTF-8 file. They’re harmless to many programs and troublesome to printers, where they can show up as a stray character or interfere with the first command. If the first label in a file is wrong and the rest are fine, suspect a BOM. Save as “UTF-8 without BOM” and retest.

4. Check the font actually has the character

If you see boxes instead of letters, you’re looking at a font problem, not an encoding problem. The font was asked for a character it doesn’t contain. Font 0 handles common Western European accents but not everything. For Greek, Cyrillic, extended Latin and most symbols, download a Unicode TrueType font. The TrueType install guide walks through it, and font not printing or showing blocks covers the diagnosis.

A tip for telling the two apart: print plain ASCII text in the same font. If “ABC 123” works but “é” shows a box, it’s coverage. If “é” shows two odd characters, it’s encoding.

5. Take the spooler out of the picture

Windows print queues, drivers and some middleware can re-encode text without telling you. Test by sending the same ZPL file directly to the printer over its raw network port, or through a raw/text-only queue. If the direct route prints correctly and the normal route doesn’t, you’ve found where the damage happens. Change the queue type or send directly from your application.

6. Use hex escapes when you can’t fix the path

When you can’t control the encoding all the way through, spell out the problem characters:

^XA
^CI28
^FO40,40^A0N,40,40^FH^FDCaf_C3_A9^FS
^XZ

^FH turns on hex mode, and _C3_A9 is how you write the two UTF-8 bytes for é in plain ASCII. It’s ugly and slow to write by hand, but it survives any pipeline. The label generator can build this for you, which is the only sane way to produce it in bulk.

7. Remember the scripts that need more than encoding

Setting ^CI28 and using a font with the right glyphs gets you Western languages, Greek, Cyrillic and many others. Arabic, Hebrew and Hindi need more: right-to-left layout, or letters that join and reorder. If those look wrong even though the encoding is right, the printer may lack the shaping support. Check language support and read our article on printing Hindi and Arabic on Zebra labels.

A test string worth keeping

Make a small label that contains the awkward characters your data really uses. Something like é ñ ü ß € £ — “quotes” catches a surprising amount. Print it after any change to fonts, firmware, software or print queue. If it comes out clean, you can relax a bit. If it doesn’t, you’ll know within a minute rather than after a pallet of labels.

Recap

The chain is: file encoding, data path, ^CI setting, font coverage. All four must agree. When something goes wrong, change one thing at a time. For the symptoms in table form, see special characters printing wrong.