Persian (RTL) characters rendering as squares in labels despite correct custom font configuration

[Ali2kCom]

First Check

• This is not a feature request
• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue and didn't find it.
• I searched the documentation, with the integrated search.
• I already read the docs and didn't find an answer.
• I can replicate the issue inside the Demo install.

Homebox Version

Nightly

What is the issue you are experiencing?

Describe the bug

I am using the Homebox Nightly build to enable the custom font feature for labels. However, Persian (RTL) characters are still rendered as squares (tofu) in the label preview, even though a compatible Unicode font (Vazirmatn) is correctly mounted and the environment variable is set.

Environment Information

• Homebox Version: Nightly
• Build ID: 2638f21
• Installation Method: Docker Compose

Expected behavior

The label generator should use the provided custom font to render Persian/Arabic characters correctly. It should also ideally handle RTL shaping (connecting characters).

Actual behavior

Persian characters are replaced by squares in the generated label image.

Additional context

It seems the current implementation might not be passing the custom font to the specific engine responsible for rendering the PNG preview or the QR code label text for non-ASCII characters.

How can the maintainer reproduce the issue?

Steps to Reproduce / My Configuration

1. Font Setup

Create a fonts directory and download a compatible Persian font (Vazirmatn):

mkdir fonts
wget https://github.com/rastikerdar/vazirmatn/raw/master/fonts/ttf/Vazirmatn-Regular.ttf -O fonts/vazir.ttf

2. Docker Compose Configuration

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:nightly
    environment:
      - HBOX_LABEL_MAKER_CUSTOM_FONT=/app/fonts/vazir.ttf
      - HBOX_STORAGE_DATA=/data
    volumes:
      - ./data:/data
      - ./fonts:/app/fonts:ro

3. Verification

I verified that the font file is accessible inside the container:

docker exec -it homebox ls -l /app/fonts/vazir.ttf

Output:

-rw-r--r-- 1 root root 122752 Dec 26 10:31 /app/fonts/vazir.ttf

4. Result

When creating an item with a Persian name (e.g., "آشپزخانه" or "تست نسخه جدید"), the label preview shows empty squares instead of Persian characters.

Deployment

Docker (Linux)

Database Type

SQLite

OS Architechture

x86_64 (AMD, Intel)

Deployment Details

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• ISSUE-1104

Related Issues

• Non-English characters (e.g., Chinese) appear as squares when downloading labels #1104
• Print label: The text in generated QRcode label does not support Chinese charactors #935

🔗 Related PRs

#1038 - Feat/Added label maker custom font [merged]

👤 Suggested Assignees

• akizono
• duchenpaul
• Rienkim

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[Kuruton8]

Hi, @Ali2kCom . Today, I had a similar problem that printed Japanese characters become tofu, as you well explained. Though my case is in LTR environment, I figured and mitigated this, so let me share.

---

Apparently, in order for printed characters to be properly displayed, we have to set different environment variables.
Set HBOX_LABEL_MAKER_REGULAR_FONT_PATH and HBOX_LABEL_MAKER_BOLD_FONT_PATH to your /path/to/font.ttf and see the result.
So, the compose file would look like this:

---
environment:
  - HBOX_LABEL_MAKER_REGULAR_FONT_PATH=/app/fonts/vazir.ttf
  - HBOX_LABEL_MAKER_BOLD_FONT_PATH=/app/fonts/vazir.ttf
#  - HBOX_LABEL_MAKER_CUSTOM_FONT=/app/fonts/vazir.ttf
---

---

I have confirmed this works for at least Japanese and Persian characters in English (en-us, LTR) environment as shown below. I'm sorry that the Persian letters printed as LTR and I haven't actually tested in RTL environment which fits yours.

Persian: Vazirmatn Font (https://github.com/rastikerdar/vazirmatn)

Japanese: IPAexフォント (https://moji.or.jp/ipafont/)

---

My environment

Deployment: Docker (Linux)
Database Type: Postgres
OS Architecture: x86_64
Homebox Version: v0.24.2

---

By the way, the environment variables I mentioned are listed in the documentation, but I think these environment variables starting with HBOX_LABEL_MAKER_ are ambiguous as they are applied to either the label generation in Homebox itself or the requests sent to "External Label Service" as explained here. The latter use is not involved in generating labels on a Homebox service side, while HBOX_LABEL_MAKER_REGULAR_FONT_PATH and HBOX_LABEL_MAKER_BOLD_FONT_PATH ARE actually used to generate labels on the Homebox side. So, I suggest we rename the environment variables in a distinctive way or document it better for clarification.