CJK and fonts
How Japanese, Simplified Chinese, Korean, and Traditional Chinese render out of the box, and how to upload custom fonts.
CJK and fonts
CJK (Chinese / Japanese / Korean) is a first-class language family, not an after-thought. Render Japanese the same way you render Latin:
{
"template": {
"page": { "size": "A4" },
"body": [{ "text": "請求書 / 인보이스 / 发票" }]
}
}
No font upload, no lang attribute, no fallback flag. The bytes are correct.
What's bundled
Out of the box, gpdf-api ships with these fonts. Glyphs are embedded into the PDF only for the codepoints actually used — there's no penalty for having a 100 MB font available if your document only contains 200 characters.
| Family | Weights | Glyphs | Typical use |
|---|---|---|---|
| Inter | Regular, Bold | Latin, Cyrillic | Default for text nodes. |
| Noto Sans JP | Regular, Bold | Hiragana, Katakana, Kanji (JIS X 0208) | Japanese. |
| Noto Sans SC | Regular, Bold | Simplified Chinese, common Hanzi | 简体中文. |
| Noto Sans KR | Regular, Bold | Hangul, Hanja | 한국어. |
| Noto Sans TC | Regular, Bold | Traditional Chinese | 繁體中文. |
| JetBrains Mono | Regular, Bold | Latin only | Code blocks, monospace. |
For mixed-language documents (a Japanese invoice with English product names) the engine picks the right font per glyph. You don't need to switch fonts manually.
How auto-fallback works
When the engine encounters a glyph the current font doesn't have, it looks up:
- The glyph's Unicode block.
- A bundled font that covers that block.
- The same weight and italic state, falling back to regular if the variant is unavailable.
If the glyph is in none of the bundled fonts (e.g. uncommon historical kanji not in Noto Sans JP), you'll see a tofu (□). To avoid that, upload a custom font that covers your glyph set — see Custom fonts.
Picking a font explicitly
Most of the time you don't have to. If you want, set style.font:
{ "text": "見積書", "style": { "font": "Noto Sans JP", "weight": "bold" }}
Valid values are family names from the table above, or any custom font you've uploaded.
| Family | Notes |
|---|---|
Inter |
Default Latin font. |
Noto Sans JP |
Latin glyphs are drawn from the JP file (slightly different metrics from Inter). |
Noto Sans SC / KR / TC |
Same idea — Latin glyphs match the CJK file. |
JetBrains Mono |
Monospace; use for code-block-style content. |
<custom name> |
The name you used at upload time. |
Custom fonts
You can upload up to 5 custom font files per account on Pro (50 on Self-host). Free does not allow custom fonts.
Upload from the dashboard at /app/fonts or programmatically:
POST /v1/account/fonts HTTP/1.1
Authorization: Bearer <firebase_id_token>
Content-Type: multipart/form-data
Content-Disposition: form-data; name="file"; filename="MyBrand-Regular.ttf"
<TTF or OTF file>
Content-Disposition: form-data; name="family"
MyBrand
Content-Disposition: form-data; name="weight"
regular
Content-Disposition: form-data; name="style"
regular
Supported formats: TrueType (.ttf), OpenType (.otf). Variable fonts (.ttf with fvar) are accepted but only the first named instance is used. WOFF/WOFF2 are not currently accepted — convert with fontforge or pyftsubset first.
A reasonable workflow:
- Subset your font to just the glyphs you need (
pyftsubsetkeeps the file under a few hundred KB). - Upload regular + bold (and italic variants if you use them).
- Reference by family name in the template's
style.font.
{ "text": "Brand title", "style": { "font": "MyBrand", "weight": "bold" }}
Subsetting and file size
The engine subsets every embedded font to only the glyphs your document actually uses. A 30 MB Noto CJK file might add only 8 KB to your output PDF if you used 50 unique characters.
If your output PDFs are unexpectedly large, check:
- Are you embedding a giant logo PNG? Most "huge PDFs" are images, not fonts.
- Are you using a font with thousands of unique CJK glyphs in a single document? Subset cost scales with unique glyphs — consider whether you really need every one of them on every page.
Line breaking and word wrap
Latin breaks on whitespace; CJK breaks on every character (with rules to avoid orphaning particles). The engine handles both:
- Latin: greedy word-wrap, with hyphenation off by default. To enable hyphenation set
style.hyphenate: true(Latin only). - Japanese: kinsoku-shori — punctuation never starts a line, opening brackets never end a line.
- Chinese / Korean: similar rules; numerals stay together.
If you need a hard break inside a text node, embed \n:
{ "text": "First line\nSecond line" }
Vertical text
Vertical Japanese (縦書き) is a v2 feature. v1 only supports horizontal layout. If you need this, drop us a line on GitHub.
Right-to-left
RTL scripts (Arabic, Hebrew) render in v1 with correct glyph ordering and bidi support, but mixed RTL/LTR alignment in tables can look off. Test before shipping.
Troubleshooting
Tofu (□) in my output
Either (a) the codepoint isn't in any bundled font and you need a custom upload, or (b) you're embedding text from a binary blob that isn't valid UTF-8. Check the raw text value.
Wrong font for English in a Japanese document The engine renders the English glyph from the same family as the surrounding CJK font. If you specifically want Inter for Latin, split the runs:
{ "row": [
{ "col": { "span": 6, "body": [{ "text": "Invoice",
"style": { "font": "Inter", "weight": "bold" }}] }},
{ "col": { "span": 6, "body": [{ "text": "請求書",
"style": { "font": "Noto Sans JP", "weight": "bold" }}] }}
]}
Bold doesn't render bold for my custom font
Make sure you uploaded the bold variant separately with weight: bold. The engine doesn't synthesise bold from a regular file — it always uses real type metrics.
Related
Something unclear or missing on this page?