feat: i18n: --lang translates report titles, headings, month names and the ui/web interfaces (#1025, #231)

[acinader]

Translations for hledger's own output text, following the list discussion
(https://groups.google.com/g/hledger/c/PmcY3J8WiDc), #1025 and #231. German is
the second language.

What it does

hledger bs --lang de:

Bilanz 2008-12-31

                    || 2008-12-31
====================++============
 Vermögen           ||
--------------------++------------
 assets:bank:saving ||         $1
 assets:cash        ||        $-2
--------------------++------------
                    ||        $-1
====================++============
 Verbindlichkeiten  ||
--------------------++------------
 liabilities:debts  ||        $-1
--------------------++------------
                    ||        $-1
====================++============
 Überschuss:        ||          0

• A new general option --lang=LANG (usable in config files) selects a
  translation catalog. It translates the compound reports' titles, section
  titles and interval words, the balance and budget report titles and their
  valuation descriptions, the Total/Average column headings and the Net: row
  in text output, month names in period headings, and FODS sheet names.
• hledger-ui translates its menu and screen names.
• hledger-web serves each request in the viewer's language: ?_LANG=de
  (remembered in a cookie), the _LANG cookie, the browser's Accept-Language,
  then the server's --lang. Pages, the add form and its validation messages,
  the help dialog and the file management pages are covered.
• Translations are gettext PO files in hledger-lib/locale/, embedded at
  build time. A user can override or add a language by dropping
  ~/.config/hledger/locale/LANG.po in place, without rebuilding: a
  translator can work against a release binary.
• English output is unchanged byte for byte: with no --lang, every lookup
  is the identity. Checked by diffing the previous build's output for a few
  dozen report invocations across output formats, and by the existing test
  suites, which pass unchanged.

Design, against the points raised on the list

• No i18n library. haskell-gettext, hgettext and i18n are all absent from the
  Stackage snapshot, and haskell-gettext last shipped in 2019. The mechanism
  is one module, Hledger.Utils.I18n, with no new dependency: a small PO
  parser (including the Plural-Forms rule), lookup functions tr, trc
  (contexts), trf ({placeholders}), trn (plurals), and language tag
  handling. The library is agent-generated (Claude Session) and
  should be agent-maintained. Goal is to make implementation compliant
  with existing tools for localization.
• Reports first, complete translations. The German catalog translates all
  180 strings. The commits are split so that the hledger-lib and CLI parts
  (commits 2 and 3) stand on their own; the hledger-ui and hledger-web
  commits can be deferred.
• --lang plus a field on ReportOpts. The field, translations_, holds the
  loaded catalog rather than a tag, because the renderers are pure and the
  catalog is loaded once in IO; the tag is inside it.
• English by default. --lang=auto, which follows LANGUAGE, LC_ALL,
  LC_MESSAGES and LANG with gettext's rules, is implemented but opt-in; I am
  happy to drop it from this PR if you would rather defer it.
• Config files: documented, with an example, in the new Languages section of
  the manual.
• --title and --subreport-titles win over translation, and number formats
  are untouched (they come from the journal).
• Titles are report data shared by every output format, so like --title
  they are translated in csv/tsv/json title rows too; column headings in
  those formats stay English. If you would rather csv stay entirely English,
  the alternative is keeping titles structured until rendering, as
  translate report texts to user language using haskell-gettext #2735
  does; that is a bigger refactor and can follow.

One deliberate divergence: PO catalogs rather than Shakespeare's .msg files.
hledger-web does use Shakespeare's I18N interface (RenderMessage, _{...}
in templates), with these catalogs behind it. PO was chosen because complete
translations come from translators, and PO is what their tools (Poedit,
Weblate) speak: it gives contexts, translator notes, a fuzzy workflow, and
lets someone test a catalog against a release without a Haskell build. My POV being
that gettext is mature and we can reliably maintain the functionality we want
with agents maintaing the i18n core code.

Docs and tooling

• Manual: a Languages section, the environment variables, the general
  options list; hledger-web's manual: a Language section.
• doc/TRANSLATING.md: a step-by-step guide for translators who are neither
  programmers nor professionals, with a worked example.
• tools/i18n-extract.py and just i18n-pot, i18n-check, i18n-merge,
  i18n-pseudo maintain the catalogs.

Tests

hledger functional suite (9 new cases in hledger/test/i18n.test),
hledger-lib unit tests for the parser, plural rules and tag handling,
hledger-web yesod tests for language selection, the cookie and a hostile
catalog rendered as text, and a Playwright spec for the German UI. All four
packages build warning-free.

Caveats

• I have not personally walked through the steps in doc/TRANSLATING.md as
  a translator would; the guide was checked mechanically (a throwaway French
  catalog placed in the config directory, exercised through --lang fr), not
  by a person following it cold.
• No performance testing. With no --lang option nothing is parsed or read,
  so the default path should be unaffected. Any --lang value, including
  en and auto, lists the override directory and parses the built-in
  catalogs (a few hundred entries). I have not measured either path.

Follow-ups

• The manual links to hledger.org/TRANSLATING.html; that needs the usual
  hledger_site symlink and SUMMARY entry, which I will open separately.
• Skills and documentation to help Agents assist with translation and
  code contributions that touch localizable strings.

Not in this PR

The hledger-ui help dialog and register labels (need a layout rework),
stats label widths, html/fods column headings, and translating error
messages or manuals.

Terminology

The German catalog uses the terms Henning chose in #2735 (Einnahmen,
Ausgaben, Einnahmenüberschussrechnung, Vermögen, Gesamt, Überschuss,
Einheit), so the two agree; see hledger-lib/locale/README.md. The one
place I kept a different word is hledger-web's account column (Konto).
examples/i18n/de.journal names its accounts aktiva and passiva, which
German speakers may want to reconcile.

AI usage: designed and implemented with Claude Code, reviewed, tested, and edited by the author.

🤖 Generated with Claude Code

https://claude.ai/code/session_01G2VXnprjHmXZR8tgWPV3vz

[acinader]

Please see https://github.com/acinader/hledger/blob/i18n-poc/doc/TRANSLATING.md as an entry point for reviewing this draft pr.

[acinader]

I don't speak French, so it's hard to tell....

Poedit tool for editing translation files.

Some screen shots

pretty cool.

[acinader]

5ef3a4e is a good example to contemplate.

1. web: balance report page (#2242) #2739 added some new text that needs to be translated. I have translated it using claude, but I have no way to actually verify.

2. This pull request adds Internationalization (i18n) capability, and it also adds a mostly "machine translated" de po.

My current take is that we should merge in the i18n stuff, and maybe include the german po file as a starter? But I wouldn't claim that we have a german localization (l10n)?

[simonmichael]

This is very comprehensive and impressive. Great work. We'll go with this for now.

Some changes/discussion needed:

• Let's follow the recent format of AI usage lines, with approximate output tokens estimates
• Let's drop the Claude-Session: URL lines, too transient (they all give me session not found).
• Everything needs to remain human-maintainable; our AI policy says we won't become dependent on AI.
• Likewise, all code needs to be reviewed and understood by humans (at least to a level of detail where we are confident in it).
  (I18n.hs looks ok at first glance.)

Bikeshedding:

• "tr translations_" everywhere is verbose - something shorter ? "tr msgs_" ? Or always define tr = I18n.tr translations_ helpers ?

Questions:

• When do you use i18n rather than tr ?

[simonmichael]

Using the english text as the keys is the the most conventional gettext approach I think. Which is generally a good thing. And it seems convenient to start with. But there will be churn when we want to tweak the ui messages. Is using a sum type of message ids, as in Henning's #2735, compatible with gettext tools ?

[simonmichael]

Let's focus on just the library and CLI reports to begin with.

[simonmichael]

Also let's defer the plural support, if not yet used (?)

But there will be churn when we want to tweak the ui messages.

Ah, but that's a good thing apparently. It signals staleness and updates needed. My claude session recommends combining a sum type for compiler checking plus english text for best translation experience:

Use a Haskell sum type for message ids, as in 2735, and make its English rendering the msgid, as in 2736. The PO files stay conventional and English-keyed. What you gain:

• Type safety. A typo or a removed message becomes a compile error. That fixes the weakest part of 2736.
• Simpler extraction. Deriving Enum and Bounded lets a small Haskell program list every message. The regex extractor, and its every-call-on-one-line rule, can go.
• No contexts. Two constructors can share English text without msgctxt, as in Henning's Total and RightTotal. Each constructor would still produce its own entry, so the catalog would need a context or the constructor name to keep them apart.
• Parameters fit. A constructor with fields, like one carrying an account name, renders to the English template plus its placeholder values.

The cost is one extra step per new string: add a constructor as well as the literal.

[simonmichael]

Then again: just writing tr before string literals in our code is a very nice gentle first step. And we don't have a huge amount of text and haven't yet experienced the problems compiler checked ids would solve. I'm fine with the current approach for now.

[simonmichael]

Thanks for the updates. I'm going to merge this as-is if you don't object. I'm feeling the need to move things along, to possibly get preview 5 out on schedule (october 1st).

[acinader]

I have a few revisions based on your comments that i am working on, so give me a little more time, but I'm on board with your plan.

…

On Tue, Sep 29, 2026 at 10:17 AM Simon Michael ***@***.***> wrote: *simonmichael* left a comment (hledgerorg/hledger#2736) <#2736 (comment)> Thanks for the updates. I'm going to merge this as-is if you don't object. I'm feeling the need to move things along, to possibly get preview 5 out on schedule (october 1st). — Reply to this email directly, view it on GitHub <#2736?email_source=notifications&email_token=AAFLBHC4VS3XCDIX3BFJXZ35RPVCJA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKOBZGUYDSNJQGYYKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-5895095060>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFLBHCTBYPLULXJAZGMSFD5RPVCJAVCNFSNUABDKJSXA33TNF2G64TZHM4TGMBRGQYTIO2JONZXKZJ3GU2DSMRXGA4TMNJRUF3AE> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AAFLBHDM32D573XJKBRC3TT5RPVCJA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKOBZGUYDSNJQGYYKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/AAFLBHGBYP4SIVZ32YOL3QL5RPVCJA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKOBZGUYDSNJQGYYKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

[simonmichael]

Or would you rather get the web prs merged first ?

[acinader]

AI usage. Done: every commit now carries the AI usage line with
a token estimate, and the session URLs are gone. The estimates are for the
tokens that produced each commit's code and text.

I have read I18n.hs; the note in the lib commit saying otherwise predated my
review. I wanted to post the PR before I had a chance to fully review I18n.hs so
we could compare to alternate implementations. I had crossed out that
disclaimer in the PR body, and have now removed it from the commit message too.

My larger point is simply that gettext is a well understood interface that
has many reference implementations and lends itself well to AI support.

Plurals. I'd rather keep trn. The Plural-Forms header is part of what
every translator's tool writes into a catalog. My strong hunch is that anyone
trying to do a full translation will require it, and our i18n machinery will be
obviously incomplete without it.

Naming. The CLI renderers now bind tr, trc, and trf to the report
options once, in a where clause, and import the module qualified, so call sites
read tr "Balance Sheet".

i18n versus tr. tr wherever the text is displayed and a Translations
value is at hand, which is nearly everywhere. i18n only marks a literal
that is stored earlier in data, before any catalog exists: the subreport
titles in the bs/is/cf specs and hledger-ui's menu items. It is the
identity; its job is to make the extractor collect the literal, which tr
then translates at display time. The module docs now say this.

My overall conclusion is that this PR puts the machinery in place at low cost
for us. Someone like @thielema can use the machinery to
do specific, incomplete translations without having to use sed on completed
reports.

The implementation is also complete enough that if someone wanted to do a
comprehensive translation, all the pieces are there. The code changes a full
translation will turn out to need can only be discovered by doing one.

Finally, I'd like this to go in before my other PRs, as it will be easier on me
to rebase the small ones than this big one.

[simonmichael]

Excellent. Thank you very much!

[simonmichael]

I'm having trouble merging the web PRs, and I see why: the line numbers in the pot file make it very conflicty. This seems like it will be a problem. Could you change the tool to omit the line numbers - not quite as convenient for translators, but I think it's needed.

[simonmichael]

Slightly related, I noticed that the texts from all --lang-supporting apps based on hledger-lib are now centralised in hledger-lib, ie hledger-lib has baked-in knowledge about things that depend on it, which is not good for modularity. But perhaps it is the pragmatic choice.

[acinader]

Well, that didn't go as smoothly as I was hoping!

I've rebased and fiddled with the open web PRs so you should now be able to merge
them all without causing any new conflicts.

#2755 now writes the template's references as file names only, no line numbers,
like xgettext's --add-location=file, so the template changes only when a
string is added, removed, or moves to another file.

Catalogs in hledger-lib: You're right that it inverts the dependency. My
thinking is one catalog per language is easier for a translator. Ideally we can keep the
single catalog for now and split it if it starts to hurt? I'm also happy to do it now if you prefer,
as I may not understand the full implications.

[simonmichael]

Great, thanks. Message ID: ***@***.***>

[simonmichael]

It seems to me that --lang is not affecting hledger-web.

[acinader]

You're browser is almost certainly sending Accept-Language: en.

I did not make --lang "win" by default and force all responses to be a particular locale.

?_LANG=xx -> cookie -> accept header -> --lang.

hledger-web --serve --lang de -f examples/sample.journal
curl -s http://127.0.0.1:5000/journal | grep -o 'lang="[a-z]*"'
curl -s -H 'Accept-Language: en' http://127.0.0.1:5000/journal | grep -o 'lang="[a-z]*"'

http://127.0.0.1:5000/journal?_LANG=de switches to Derman and sets a cookie to remembers the choice.