# 0021. Languages and Chinese printing

- Status: Accepted
- Date: 2026-10-28

## Context

Malaysian shops work in English, Malay and Chinese, often all three in one shop: a cashier
reads Malay, the kitchen reads Chinese, and customers want receipts they can read. M8 adds
Malay (`ms`) and Simplified Chinese (`zh-Hans`) to the POS app, the back office and the printouts.
Each reader needs their own language, and switching must not need a restart.

Thermal printers mostly print only Latin text in their built-in fonts. Models made for the Chinese
market also have a Chinese font (GB2312/GBK, read in their "Chinese mode"), but many printers sold
in Malaysia don't. Printing Chinese must work on both, without native code that can only be
checked on a device.

## Decision

**Who chooses which language.**
- **Device screens:** each POS device chooses its own screen language. It is stored on the
  device, offered on the setup screen, the PIN pad and in Settings → Language, and starts from
  the system language.
- **Back office:** each browser chooses its own language. It is stored in the browser and starts
  from the browser's language.
- **Shop settings:** the shop sets a receipt language, an optional second receipt language, and
  a kitchen ticket language. The kitchen ticket language defaults to the receipt language.
  These settings sync like the other shop settings.
- **Z-reports and test pages:** these are for staff, so they print in the device's screen
  language.

**Switching without a restart.**
- **POS app:** the provider holds the translator, so every screen re-renders when it changes.
- **Back office:** the router remounts with the new language (the data cache stays), and `<html
  lang>` follows.
- **Hub errors:** the hub answers in the language a request asks for (`Accept-Language`). The back
  office and the app send theirs, so errors appear in the reader's language. Handlers send catalog
  keys (`fail("server.…")`), and one hook turns them into words.

**Two languages on a receipt.** With a second language, labels print in both ("Total / Jumlah").
A label followed by one value prints in both, with the value once ("Receipt / Resit K1-0042",
"Served by / Dilayan oleh Aminah"; changed 2026-10-28, after the third Mac pass found those
lines in one language). Messages with several values (tax lines) print in the first language
only, so numbers aren't printed twice. Lines that grow too long wrap. Item names are the shop's
own data and print as entered.

**Catalogs.**
- **Layout:** every language has the same keys, split into the POS app, printing, the back
  office and the hub's messages.
- **Tests:** they check that each language has every key with the same placeholders.
- **No hard-coded text:** a test scans the POS app's and back office's components for text
  written into JSX or into props people read (`label`, `title`, `placeholder`, `aria-label`…).

**Chinese printing.** Each printer chooses one of two modes:
- **Image (the default):** works on every printer that prints images (`GS v 0`), which is all
  the printers we target. A line containing Chinese is drawn as a 1-bit image at the printer's
  own cell size (12 × 24 dots, wide characters 24 × 24) and sent like a QR image, so columns line
  up with lines the printer draws itself. The glyphs are GNU Unifont's 16-dot bitmaps (SIL OFL
  1.1), scaled 1.5× with smoothing.
- **Printer's own font:** for printers with a Chinese font. The line is sent in Chinese mode
  (`FS &`) with GBK bytes, then the job leaves Chinese mode again (`FS .`).

**What the font covers.** GBK: simplified and traditional Chinese, which includes GB2312 and is
read by GB18030 printers. GB2312 alone would miss characters common on Malaysian menus, such as
粿 in 炒粿条 and 叻 in 叻沙. The glyphs and the GBK table are packed into one generated module of
about 580 KB (deflated, base64). It is unpacked into flat arrays the first time Chinese is
printed.

## Consequences

- **Printing:**
  - Every printer can print Chinese out of the box, with no native code and no new permissions.
  - Image lines print a little slower than text and look pixelated next to the printer's own
    font. Shops with a Chinese printer can switch that printer to its own font.
  - Characters outside GBK print as "？". Emoji are among them.
  - Unifont's Latin glyphs, used in image lines, don't match the printer's own font exactly.
- **Size:**
  - The POS app's JavaScript grows by about 580 KB for the font.
  - The back office grows by about 70 KB for the extra languages, now one 510 KB file (150 KB
    gzipped).
- **Translations:**
  - Plugin labels already carry `en`, `ms` and `zh-Hans` (ADR 0018). They now follow the
    screen's language on screens and the receipt language on receipts.
  - Sample menu items, staff names and other shop data are not translated.
  - Adding a language means a catalog, a tag in `LOCALES`, and a review of receipt widths
    (labels must fit a 32-column line).
- **Hub API:** catalog keys for errors are part of how the hub talks. Plugins still send their
  own words.