Skip to main content

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

zpl
^XA
^CF0,50
^FO40,40^FDÉcrou hexagonal M8^FS
^CF0,40
^FO40,120^FDBoîte de 100 : 5,90 €^FS
^XZ

Sent 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

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
  • ^CI28 tells the printer the field data is UTF-8. Put it after ^XA and 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 ^CI28 after ^XZ. A later label from other software that sends its text in the printer's code page would then be read as UTF-8. ^CI0 before ^XZ sets the printer back to its factory default. If your printers were set to another code page and saved with ^JUS, end with that ^CI value 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 €:

zpl
^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
^XZ

Firmware 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.

zpl
^XA
^CF0,50
^FO40,40^FH_^FD_90crou hexagonal M8^FS
^CF0,40
^FO40,120^FH_^FDBo_8Cte de 100 : 5,90 EUR^FS
^XZ

Under ^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.

json
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:

zpl
^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
^XZ

Send 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 200 with the ZPL as plain text. A request the API cannot turn into a label answers 400 with 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 maxLength on 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.