Como usar IPAex Gothic no gpdf?

A pergunta, em outras palavras

Você quer usar a IPAex Gothic — a fonte Gothic proporcional que a Information-technology Promotion Agency (IPA) do Japão mantém — em um documento gpdf. Motivos típicos: envios de PDF para o e-Tax, papelada para órgãos governamentais, ou um guia de estilo interno que vive com IPAex desde o início dos anos 2010. Três coisas costumam atrapalhar: qual arquivo pegar, como lidar com a ausência de Bold e o que a IPA Font License realmente te pede.

TL;DR

Registre ipaexg.ttf com gpdf.WithFont("IPAexGothic", bytes). Defina como padrão. O negrito precisa ser sintetizado com template.Bold() ou pareado com IPAex Mincho, já que IPAex só publica Regular. Mantenha o texto da licença junto do binário.

O exemplo completo

package main

import (
    "log"
    "os"

    "github.com/gpdf-dev/gpdf"
    "github.com/gpdf-dev/gpdf/document"
    "github.com/gpdf-dev/gpdf/template"
)

func main() {
    font, err := os.ReadFile("ipaexg.ttf")
    if err != nil {
        log.Fatal(err)
    }

    doc := gpdf.NewDocument(
        gpdf.WithPageSize(gpdf.A4),
        gpdf.WithMargins(document.UniformEdges(document.Mm(25))),
        gpdf.WithFont("IPAexGothic", font),
        gpdf.WithDefaultFont("IPAexGothic", 10.5),
    )

    page := doc.AddPage()
    page.AutoRow(func(r *template.RowBuilder) {
        r.Col(12, func(c *template.ColBuilder) {
            c.Text("請求書", template.FontSize(24), template.Bold())
            c.Text("令和8年4月17日発行")
            c.Text("金額: ¥100,000 (税込)")
        })
    })

    data, err := doc.Generate()
    if err != nil {
        log.Fatal(err)
    }
    if err := os.WriteFile("invoice.pdf", data, 0o644); err != nil {
        log.Fatal(err)
    }
}

Baixe IPAex00401.zip em moji.or.jp/ipafont, extraia ipaexg.ttf, coloque ao lado de main.go e rode go run main.go.

Qual arquivo IPA é o certo

Ao abrir o zip, você tem três TTFs mais uma licença. As pessoas confundem constantemente:

O "ex" em IPAex significa "extended proportional". As fontes IPA originais colocavam os caracteres latinos em grades CJK de largura fixa, fazendo o texto misto J/E parecer esticado. IPAex corrige isso tornando os caracteres latinos proporcionais enquanto mantém os CJK na grade normal. Para qualquer documento com palavras em inglês, URLs ou números — ou seja, basicamente todo documento de negócio no Japão — você quer IPAex.

Se você herdou um projeto que usa ipag.ttf porque o engenheiro que escolheu a fonte fez isso antes de IPAex existir (IPA Gothic original: 2003, IPAex: 2010), a troca é um swap de arquivo. Mesmo nome de família, tudo igual.

Sem arquivo Bold — e agora?

IPAex publica exatamente um peso por família: Regular. É incomum comparado aos nove pesos da Noto Sans JP, e é o principal motivo pelo qual as pessoas olham para IPAex e decidem que não dá para usar.

Duas formas de lidar no gpdf:

Negrito sintetizado. template.Bold() aplica um traço sobre os glifos Regular. Tipograficamente é uma trapaça — pesos bold reais têm contornos redesenhados com traços mais grossos, não Regular traçado duas vezes. Mas para títulos de fatura e rótulos de tabela a 10 pt ou mais, o bold sintetizado é indistinguível para a maioria dos leitores:

c.Text("合計金額", template.Bold())

Pareamento com IPAex Mincho. O recurso clássico da tipografia japonesa para ênfase não é negritar — é alternar serif/sans. Registre as duas famílias:

gothic, _ := os.ReadFile("ipaexg.ttf")
mincho, _ := os.ReadFile("ipaexm.ttf")

doc := gpdf.NewDocument(
    gpdf.WithFont("IPAexGothic", gothic),
    gpdf.WithFont("IPAexMincho", mincho),
    gpdf.WithDefaultFont("IPAexGothic", 10.5),
)

page.AutoRow(func(r *template.RowBuilder) {
    r.Col(12, func(c *template.ColBuilder) {
        c.Text("請求書", template.FontFamily("IPAexMincho"), template.FontSize(24))
        c.Text("ご請求内容は下記の通りです。")
    })
})

É o visual que se vê em convites de casamento e relatórios formais japoneses — Mincho para títulos, Gothic para corpo. Se seu documento vai para um órgão público, essa é provavelmente a combinação que eles esperam.

A IPA Font License, rapidamente

IPAex não é SIL OFL. É a IPA Font License Agreement v1.0, aprovada pela OSI e em geral permissiva, mas com duas exigências que vale nomear:

1. Preserve o texto da licença onde quer que você distribua o binário da fonte. Se você //go:embed o TTF, empacote também o arquivo de licença. Um LICENSES/IPA-FONT-1.0.txt na raiz do projeto atende a maior parte dos casos.
2. Não renomeie a fonte. Se você modificar o próprio TTF e redistribuir, o derivado precisa ter um nome diferente (sem conter "IPA" ou "IPAex"). Atenção: essa restrição não se aplica ao subset de glifos feito em tempo de render. O artigo 3.4 da licença isenta explicitamente os documentos de saída criados com a fonte dessa restrição de nomes.

Ou seja: o subset do gpdf em doc.Generate() está OK. O subset da fonte que fica embutido no seu PDF não precisa de outro nome e não dispara as cláusulas de "Derivative Font Program". Você está criando um documento, não redistribuindo uma fonte.

Um detalhe para quem contribui com o gpdf em si: evitamos colocar IPAex no repositório do gpdf (os testes de golden usam fontes SIL OFL como Noto) justamente para que usuários a jusante não precisem pensar na compatibilidade de licença com o LICENSE raiz do próprio projeto. Se você usa IPAex na sua aplicação, a decisão é do seu projeto, não nossa.

Quando escolher IPAex no lugar de Noto Sans JP

Escolha IPAex quando sua saída atravessa uma fronteira institucional japonesa — envios de PDF para e-Tax, peças processuais, artigos para revistas japonesas — porque avaliadores, revisores e ferramentas de OCR nesses ecossistemas estão calibrados em IPA. Para o resto, Noto Sans JP. Renderizam muito parecido; a escolha é de encaixe no ecossistema, não estética.

Leituras relacionadas

• Como incorporar uma fonte japonesa no gpdf? — a receita geral, serve para qualquer TTF CJK
• Como usar Noto Sans JP com o gpdf? — a alternativa SIL OFL com nove pesos
• Por que meu PDF mostra retângulos no lugar de japonês? — troubleshooting quando os glifos não aparecem
• Guia de fontes — referência completa de WithFont

Experimente o gpdf

gpdf é uma biblioteca Go para gerar PDFs. Licença MIT, zero dependências externas, suporte nativo a CJK.

go get github.com/gpdf-dev/gpdf

⭐ Star no GitHub · Ler a documentação