Internationalization

[Henning Thielemann]

Currently I translate Hledger incomestatement reports to German using
search&replace as postprocessing. It would nice to directly generate
reports in German.

There are already open issues for that matter:
https://github.com/hledgerorg/hledger/issues/1025
https://github.com/hledgerorg/hledger/issues/231

The Haskell Wiki page
https://wiki.haskell.org/Internationalization_of_Haskell_programs

mentions essentially three approaches:

1. gettext/hgettext

2. Yesod/Shakespeare

3. Grammar Framework


Of the gettext approach I like that people can add translations for new
languages without recompiling Hledger. However, gettext seems to use a
global variable for the locale and thus it is not thread-safe and not
appropriate for hledger-web, that has to ship to different locales
concurrently. The Wiki page warns that gettext is not well supported on MS
Windows.

Simon Michael mentions https://projectfluent.org/ in a comment.


I see there are two different places for localization:

1. The user interface of hledger tools.

2. The reports generated by hledger.

Currently I am only concerned with the second item. Localization also
concerns the way figures are formatted, e.g. English "12.34 EUR" vs.
German "12,34 EUR".


Any opinions what is currently the best way for internationalization in
Haskell?

[Arthur Cinader]

The gettext global in hledger-web would presumably be scoped to a request.

I can take a look at a POC to see how the plumbing would work.

[Simon Michael]

This has always been a goal, so thanks for raising it. I did some quick research. Here's my 2c:

- Don't bother with heavy/undermaintained/static i18n libs

- Shakespeare's I18N module looks good, and is already a dependency of hledger and hledger-web

  (https://hackage-content.haskell.org/package/shakespeare-2.2.0/docs/Text-Shakespeare-I18N.html)

- Focus strictly on text in reports for now, starting with bs/is/cf - titles, headings, month names, weekday names.  Ignore CLI, error messages, docs. Catalogue the reports and report items to be translated. 

- Translate these into one or two new languages, completely. (Let's only ever ship complete translations.)

- Select the display language at runtime with a _lang in ReportOptions, and a --lang CLI option.

- Don't switch based on locale - default to english for consistency and repeatability. We'll document how to set --lang in a config file.

--

You received this message because you are subscribed to the Google Groups "hledger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to hledger+u...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/hledger/4d0629ed-7082-4b8b-aa31-e22734503637n%40googlegroups.com.

[Simon Michael]

On Wed, Sep 16, 2026, at 13:13, Simon Michael wrote:

- Don't switch based on locale - default to english for consistency and repeatability. We'll document how to set --lang in a config file.

For now, anyway. We could consider adding --lang=auto later.

Some related things that exist:

- --title and --subreport-titles

- commodity display styles and international number formats

- open i18n issues: https://github.com/hledgerorg/hledger/issues?q=state%3Aopen%20label%3A%22i18n%22

[Arthur Cinader]

helpful input. thanks.

[Henning Thielemann]

On Wed, 16 Sep 2026, Simon Michael wrote:

> This has always been a goal, so thanks for raising it. I did some quick research. Here's my 2c:
>
> - Don't bother with heavy/undermaintained/static i18n libs

> - Shakespeare's I18N module looks good, and is already a dependency of hledger and hledger-web
>   (https://hackage-content.haskell.org/package/shakespeare-2.2.0/docs/Text-Shakespeare-I18N.html)

I already started my draft when you answered. After evaluating the
alternatives I ruled out Shakespeare because it requires that all
languages are baked into the Hledger executable. In contrast to that I
think it is essential that users can create their own translations, maybe
even custom translations for their specific needs.

Here is my first draft:
https://github.com/hledgerorg/hledger/pull/2735

However, since Shakespeare can evaluate arbitrary Haskell code it would be
capable of doing a little language processing (see below).

> - Focus strictly on text in reports for now, starting with bs/is/cf -
> titles, headings, month names, weekday names. 

I started with this, but even things like "Monthly Income Statement"
cannot be easily translated because attributes like "Monthly" need to be
adapted to the gender of noun in many languages.

Also, translations for Month and Weekday names already exist in glib20.mo.
I am not sure whether we should re-use such generic translations or
include our own ones.

> Ignore CLI, error messages, docs. Catalogue the reports and report items to be translated. 

Error messages in the sense of Haskell's "error" are messages to the
developer and should not be translated. In the long run however, user
error messages should be translated. I am afraid Hledger does not clearly
separate these two kinds of errors.

> - Select the display language at runtime with a _lang in ReportOptions, and a --lang CLI option.
> - Don't switch based on locale - default to english for consistency and repeatability. We'll document how to set
> --lang in a config file.

Currently I let the user choose a catalog file.

[Arthur Cinader]

I was working through Simon's comments. I will stop now and get a presentable draft pr asap. I haven't looked at your pr in detail, but I will after posting so we can compare and discuss. Awesome! (ps I don't speak German, so I am going to steal your translations :)).

[Henning Thielemann]

On Thu, 17 Sep 2026, Arthur Cinader wrote:

> I was working through Simon's comments. I will stop now and get a
> presentable draft pr asap. I haven't looked at your pr in detail, but I
> will after posting so we can compare and discuss. Awesome! (ps I don't
> speak German, so I am going to steal your translations :)).

I am curious to see your approach. Feel free to add a translation to your
language.

[Henning Thielemann]

On Thu, 17 Sep 2026, Arthur Cinader wrote:

> I was working through Simon's comments. I will stop now and get a
> presentable draft pr asap. I haven't looked at your pr in detail, but I
> will after posting so we can compare and discuss. Awesome! (ps I don't
> speak German, so I am going to steal your translations :)).

If you are using Shakespeare and an enumeration for the messages you might
re-use this one:

https://github.com/hledgerorg/hledger/pull/2735/changes/d062218dad6475e99e300cfa7c81275ebe483b97#diff-426b5678d04128f870079c0c3dac6116f941dfef20d42c7bc0f34b8af1c1aaa3

[Simon Michael]

-

On Thu, Sep 17, 2026, at 07:52, Henning Thielemann wrote:
> I already started my draft when you answered. After evaluating the
> alternatives I ruled out Shakespeare because it requires that all
> languages are baked into the Hledger executable. In contrast to that I
> think it is essential that users can create their own translations, maybe
> even custom translations for their specific needs.
>
> Here is my first draft:
> https://github.com/hledgerorg/hledger/pull/2735

Thanks! I will look at this when I can. Apologies, I am backlogged.

When you say "users can create their own translations", do you mean without recompiling hledger ? I wouldn't see that as essential.

Custom translations for specific needs - I don't see this as an essential feature we need to deliver.

Isn't it good enough, in line with our philosophy of easy UX, and a great improvement, if we ship with some (growing) number of standard translations out of the box ?

I really think we'll want the dynamism (of shakespeare, eg) to handle tricky cases at runtime. But TBD.

[Simon Michael]

PS for me, internationalising error messages or UI elements are deliberately right out of scope for now. It's too much to think about. It might be that a combination of i18n technologies might be useful eventually..

> --
> You received this message because you are subscribed to the Google
> Groups "hledger" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to hledger+u...@googlegroups.com.
> To view this discussion visit

> https://groups.google.com/d/msgid/hledger/6607fc9c-b993-4593-bf23-871d50f4ce70%40app.fastmail.com.

[Chunhui Ouyang]

Can I say something? When I saw this sentence of yours:

> When you say "users can create their own translations", do you mean
without recompiling hledger ? I wouldn't see that as essential.

It would of course be very cool if users could create translation files
with minimal effort without recompiling. This means that users can
completely customize their own translation files without recompiling
hledger itself. At most, they only need to compile the translation files.

Chunhui Ouyang
www.qhjack.top <https://www.qhjack.top>

[Henning Thielemann]

On Fri, 18 Sep 2026, 'Chunhui Ouyang' via hledger wrote:

> Can I say something? When I saw this sentence of yours:
>
>> When you say "users can create their own translations", do you mean without
> recompiling hledger ? I wouldn't see that as essential.
>
> It would of course be very cool if users could create translation files with
> minimal effort without recompiling. This means that users can completely
> customize their own translation files without recompiling hledger itself. At
> most, they only need to compile the translation files.

Yes, I think that there are enough people out there who never installed
gigatons of GHC and Haskell libraries and do not plan to do so. And the
gettext solution really has a minimal time from changing a translation to
watching whether the generated reports are as expected.

[Henning Thielemann]

On Fri, 18 Sep 2026, Chunhui Ouyang wrote:

>> Yes, I think that there are enough people out there who never installed
>> gigatons of GHC and Haskell libraries and do not plan to do so. And the
>> gettext solution really has a minimal time from changing a translation
>> to watching whether the generated reports are as expected.
>

> gettext might be a good solution. In C/C++ another solution is ICU but I'm
> not sure if haskell can use ICU

There is:
https://hackage.haskell.org/package/text-icu

[Chunhui Ouyang]

Oh, then we can consider the ICU internationalization plan

[Arthur Cinader]

https://github.com/hledgerorg/hledger/pull/2736

My approach is focused on the translator. I haven't run through it all yet, but I wanted to post it as an alternative approach for discussion.

My hunch is that this is a particularly well-suited issue for AI, as it is a well-understood problem.  The guts can be agent-maintained, and the user interface is pre-defined and industry-standard.

 https://claude.ai/code/session_01G2VXnprjHmXZR8tgWPV3vz

Start with: https://github.com/acinader/hledger/blob/i18n-poc/doc/TRANSLATING.md

[Arthur Cinader]

If you're interested, you can check it out and take it for a spin...

https://github.com/acinader/hledger/blob/i18n-poc/doc/TRANSLATING.md

[Arthur Cinader]

Enabling translators to use standard translation tools and be able to see incremental edits without a compile is important if we want to see hledger broadly translated. It lowers the bar. 

Also, yes, allowing someone to drop a translation file in their config to get what they want is a good feature on its own.