ZPL how-to
Accented characters in ZPL (^CI28)
A Zebra printer reads field data in its own code page unless the label says otherwise. Send it UTF-8 text, as almost every program does today, and each accented letter prints as two or three wrong characters.
What goes wrong
^XA
^CF0,50
^FO40,40^FDÉcrou hexagonal M8^FS
^CF0,40
^FO40,120^FDBoîte de 100 : 5,90 €^FS
^XZSent as UTF-8, this prints ├ëcrou for Écrou, Bo├«te for Boîte and Ôé¼ for the euro sign. In UTF-8 each of those characters is two or three bytes, and the printer draws every byte as a character of its default code page.
In plain ZPL
^XA
^CI28
^CF0,50
^FO40,40^FDÉcrou hexagonal M8^FS
^CF0,40
^FO40,120^FDBoîte de 100 : 5,90 €^FS
^CI0
^XZ^CI28tells the printer the field data is UTF-8. Put it after^XAand before the first field that needs it.- Send the ZPL as UTF-8 bytes: in C#,
Encoding.UTF8.GetBytes; in Python,.encode('utf-8'). Encoding it some other way brings the problem back. - The printer keeps
^CI28after^XZ. A later label from other software that sends its text in the printer's code page would then be read as UTF-8.^CI0before^XZsets the printer back to its factory default. If your printers were set to another code page and saved with^JUS, end with that^CIvalue instead. - It needs Zebra firmware V60.14, V50.14 or later. The printer's configuration label shows the firmware version.
When you cannot send UTF-8
If something between your code and the printer mangles bytes above 127, write them as hex escapes under ^FH, so the ZPL itself stays plain ASCII. These are the UTF-8 bytes of É, î and €:
^XA
^CI28
^CF0,50
^FO40,40^FH_^FD_C3_89crou hexagonal M8^FS
^CF0,40
^FO40,120^FH_^FDBo_C3_AEte de 100 : 5,90 _E2_82_AC^FS
^CI0
^XZFirmware older than x.14 has no UTF-8. Leave out ^CI28 and write each accented letter as its single byte in the printer's default code page, Code Page 850: É is _90 and î is _8C. Code Page 850 covers Western European letters but has no euro sign, so this sample spells it out.
^XA
^CF0,50
^FO40,40^FH_^FD_90crou hexagonal M8^FS
^CF0,40
^FO40,120^FH_^FDBo_8Cte de 100 : 5,90 EUR^FS
^XZUnder ^FH a ^, ~ or underscore in the data needs an escape too, as the guide on printing them explains.
Other alphabets
^CI28 passes any character to the printer, but the font has to contain it. Font 0 covers Latin, Greek and Cyrillic. It has no Chinese, Japanese or Korean characters: in Labelary they print as blank space, with no error. To print them, load a font that has them on the printer and select it for the field, with ^A@ or a name given to it with ^CW.
The same label with zeepler
Send this body to POST https://api.zeepler.com/v1/zeeplify with your API key in the x-api-key header. It is a working request, not an illustration: on every change, our tests run this same file through the API's code and compare the result with the ZPL below.
1{2 "config": {3 "size": "4x2"4 },5 "data": {6 "product": "Écrou hexagonal M8",7 "pack": "Boîte de 100 : 5,90 €"8 },9 "templates": [10 {11 "type": "Text",12 "dataPath": "product",13 "coords": [40, 40],14 "font": "0,50"15 },16 {17 "type": "Text",18 "dataPath": "pack",19 "coords": [40, 120],20 "font": "0,40"21 }22 ]23}And the ZPL that comes back, ready to send to the printer:
^XA^MCY^XZ
^XA
^SZ2
^MMT
^MNY
^LL406
^PW812
^LH0,0
^CI28
^CF0,50^FO40,40^FDÉcrou hexagonal M8^FS
^CF0,40^FO40,120^FDBoîte de 100 : 5,90 €^FS
^CI0
^XZSend the values as they are. When any value has a character outside ASCII, zeepler's ZPL puts ^CI28 before the first field and ^CI0 before ^XZ, so the printer reads it as UTF-8 and is switched back to its factory default for the next job. A label with only ASCII text carries neither.
The response is UTF-8, so send it to the printer as UTF-8 bytes. On firmware older than x.14, accented letters from zeepler still print wrong: it does not write Code Page 850 escapes.
Sending it
- Call the API from your own server or integration engine, not from a web page. An API key in a browser is a key anyone can copy.
- A successful call answers
200with the ZPL as plain text. A request the API cannot turn into a label answers400with every problem listed by field, and is not billed. - Send the ZPL to a Zebra or other ZPL printer at 203 dpi. At 300 dpi the same label prints at two-thirds of the size.
The API reference has every field and status code.
Before you go live
- Print a label with your real values on each printer model you use, and check every accented letter.
- Text does not wrap. A value longer than the space you left runs off the edge of the label, so set
maxLengthon any field whose length you do not control. - Coordinates are in dots from the top-left corner. Print one label, measure it, and adjust: there is no preview.
- Scan every barcode and QR code on a printed label before relying on it.
Related guides
- QR code size in ZPL: How ^BQ magnification sets the size of a QR code, and how to work out the size in dots.
- Printing ^, ~ and _ in ZPL: Why a caret or tilde in your data cuts the field short, and how ^FH prints them.
- Font size in ZPL: Setting text height with ^A and ^CF, converting points to dots, and why ^CF carries over.
- Send ZPL to a Zebra printer from C#: Send ZPL from .NET to a network printer on port 9100, or to a USB printer through the Windows spooler, without the driver redrawing it.
- Code 128 barcodes in ZPL: Set a Code 128 barcode's width and height with ^BY and ^BC, work out its width in dots, and pick subsets A, B and C.
- Send ZPL to a Zebra printer from Python: Send ZPL from Python to a network printer on port 9100, or to a USB printer through the Windows spooler, without the driver redrawing it.
- Change a barcode to a QR code in ZPL: Swap ^BC for ^BQ, start the field data with QA, so the first characters scan, and reset the ^BY left over from the barcode.
Help with an integration
Email info@zeepler.com. You will get a reply within 2 business days. The support policy covers response times and version changes.