Prepare for language translations #2242

afh · 2023-04-16T17:53:35Z

This PR adds support for international languages by fully enabling gettext support in Ledger.

Since this is a larger PR I'll tag is as a draft, so folks can chime in and provide feedback.

The changes are widespread throughout the codebase as the way that Ledger's creates its output messages had to change. Please review the inline comments on this PR for questions, details of note, and further context on the thinking that went into this PR.

Some of Ledgers messages were pieced together in output streams, yet to better support translations to languages that have a grammar that is very different from English or similar Roman languages the use of format strings is preferred. Other messages would benefit from comments made available to translators as to provide
more context about the message and its placeholder parameters.

Example:

	`src/draft.cc`
Before	`out << _("Date: ") << *date << std::endl;`
After	`out << _f("Date: %1%") % *date << std::endl;`

Closes #1241

TODO:

Address all added TODOs

☝️P.S.: This is the result of a few days work on many areas of the code, hence I kindly request thorough review should something have slipped my attention, while wrangling all the necessary changes to make this a reality.

✌️P.P.S.: ~~separate PR will follow that adds the first international language to Ledger.~~ See #2243

in version.texi.in

according to recommendations from https://www.gnu.org/software/gettext/manual/gettext.html#Preparing-Strings

afh · 2023-04-16T18:29:56Z

.gitignore

@@ -66,7 +66,6 @@ m4/
 make.sh
 missing
 mkinstalldirs
-po/


Are we okay with re-introducing the po/ directory again? If not what would be a preferred location in the repository?

afh · 2023-04-16T18:30:51Z

doc/LedgerVersion.cmake

@@ -3,3 +3,4 @@ set(Ledger_VERSION_MINOR 3)
 set(Ledger_VERSION_PATCH 2)
 set(Ledger_VERSION_PRERELEASE "")
 set(Ledger_VERSION_DATE  20230330)
+set(Ledger_VERSION "${Ledger_VERSION_MAJOR}.${Ledger_VERSION_MINOR}.${Ledger_VERSION_PATCH}")


This is for convenience, as much as I enjoy typing it gets tedious at some point.

afh · 2023-04-16T18:35:19Z

po/CMakeLists.txt

+          --keyword='_'
+          --keyword='_f'
+          --keyword='_n:1,2'
+          --keyword='_fn:1,2'


The keywords refer to the special custom macros for gettext functions defined in system.hh.in:200ff

afh · 2023-04-16T18:36:29Z

po/README.md

@@ -0,0 +1,55 @@
+# Support for International Languages


Reviewers: What is missing from this file that would be helpful for developers, collaborators, translators that wish to update Ledger's codebase and/or translations?

afh · 2023-04-16T18:37:10Z

src/account.h

@@ -103,7 +103,8 @@ class account_t : public flags::supports_flags<>, public scope_t
  virtual ~account_t();

  virtual string description() {
-    return string(_("account ")) + fullname();
+    // TRANSLATORS: %1% refers to the full name of the account


These special TRANSLATORS comments show up in the .po files and provide context for translators. Ideally this is done for the majority of the messages, but as this is quite an effort I wanted to get 👀 on these changes to verify that this is headed into the right direction.

afh · 2023-04-16T18:38:50Z

src/draft.cc


      if (post.amount)
-        out << _("  Amount:       ") << *post.amount << std::endl;
+        out << indent << _f("Amount:       %1%") % *post.amount << std::endl;


I believe the indentation should not be part of the translatable string; do people dis/agree?

afh · 2023-04-16T18:42:16Z

src/global.h

+#if HAVE_BOOST_PYTHON
+      << _("and with Python support")
+#else
+      << _("and without Python support")


I don't like how the message for Ledger's gpg and Python capabilities is pieced togeher.

Neovim's output with the -v option includes a "Features" line, e.g. Features: +acl +iconv +tui. For Ledger this could be: Features: +gpg +py is this an improvement over the current output?

afh · 2023-04-16T18:43:14Z

src/gpgme.cc

+    // TRANSLATORS: This is an error message when the gpgme encryption library
+    // could not be initialized.
+    // %1% refers to the source of the error
+    // %2% refers to the actual error as a string.
    throw_(runtime_error, _f("%1%: %2%") % err.source() % err.asString());


Should this be changed to something like:

Suggested change

throw_(runtime_error, _f("%1%: %2%") % err.source() % err.asString());

throw_(runtime_error, _f("Unable to initalize GPG at %1%: %2%") % err.source() % err.asString());

afh · 2023-04-16T18:44:56Z

src/journal.cc

+              // %2% refers to the value of the metadata
+              // %3% [Unknown]
+              _f("Metadata assertion failed for (%1%: %2%): %3%")
+               % key % value % (*i).second.first);


@jwiegley What does (*i).second.first) refer to?

afh · 2023-04-16T18:45:38Z

src/main.cc

-  ::textdomain("ledger");
+  ::setlocale(LC_MESSAGES, "");
+  ::bindtextdomain(GETTEXT_DOMAIN, GETTEXT_LOCALE_DIR);
+  ::bind_textdomain_codeset(GETTEXT_DOMAIN, "UTF-8");


Is it safe to always use the UTF-8 codeset?

afh · 2023-04-16T18:46:21Z

src/py_amount.cc

-         _("Construct an amount object whose display precision is always equal to its\n\
-internal precision."))
+         "Construct an amount object whose display precision is always equal"
+         "to its\ninternal precision.")


I believe DocStrings should be in English and not be translated.

afh · 2023-04-16T18:46:27Z

src/py_amount.cc

    .staticmethod("exact")

    .def(init<amount_t>())

    .def("compare", &amount_t::compare, args("amount"),
-         _("Compare two amounts for equality, returning <0, 0 or >0."))
+         "Compare two amounts for equality, returning <0, 0 or >0.")


afh · 2023-04-16T18:47:13Z

src/stats.cc

@@ -55,61 +55,58 @@ value_t report_statistics(call_scope_t& args)
  assert(is_valid(statistics.earliest_post));
  assert(is_valid(statistics.latest_post));

-  out << format(_f("Time period: %1% to %2% (%3% days)")


@jwiegley Can you thing of a reason why the outer format may have been significant?

afh · 2023-04-16T18:49:25Z

src/value.cc

@@ -1341,7 +1341,7 @@ void value_t::in_place_not()
    break;
  }

-  add_error_context(_f("While applying not to %1%:") % *this);
+  add_error_context(_f("While applying 'not' to %1%:") % *this);


@jwiegley The quoting within Ledger's messages is a bit inconsistent. From what I can tell most messages use single quotes and a few double quotes.
This PR maintains compatibility with previous versions.
Are you okay with deciding on one type of quotes (my preferences: 'single') and change all the double quotes to single quotes within Ledger's messages?

Also I think there are a few messages that refer to a ledger key word (like not here), but do not quote it. I believe being consistent here and quoting all Ledger keywords will be helpful for users and translators.

afh · 2023-04-16T21:15:23Z

CMakeLists.txt

+  if(CMAKE_INSTALL_LOCALEDIR)
+    set(GETTEXT_LOCALE_DIR "${CMAKE_INSTALL_LOCALEDIR}")
+  else()
+    set(GETTEXT_LOCALE_DIR "FIXME")


What is a sensible default here?

Suggested change

set(GETTEXT_LOCALE_DIR "FIXME")

set(GETTEXT_LOCALE_DIR "locale")

afh · 2023-04-16T21:16:42Z

src/item.cc

    return empty_string;

  assert(len < 1024 * 1024);

  std::ostringstream out;

  if (item.pos->pathname.empty()) {
-    out << desc << _(" from streamed input:");
+    // FIXME: Find out what `desc` represents and update comment for translators


@jwiegley Can you provide more information what values desc can hold? I assume the variable name is an abbreviation of description, yet that does not tell a translator much about how to best fit this piece into a sentence…

afh added 4 commits April 16, 2023 09:27

Add and make use Ledger_VERSION CMake variable

0084d3d

in version.texi.in

Prepare translatable strings

5c77583

according to recommendations from https://www.gnu.org/software/gettext/manual/gettext.html#Preparing-Strings

Enable support for gettext and update to 0.20.1

953b88a

Add support or translation files

5bd6539

afh added the enhancement New feature or request label Apr 16, 2023

afh requested review from a team April 16, 2023 17:53

afh self-assigned this Apr 16, 2023

This was referenced Apr 16, 2023

Prepare for language translations #2241

Closed

Add German translation #2243

Draft

afh commented Apr 16, 2023

View reviewed changes

Merge branch 'master' into prepare-for-language-translations

3ad8f28

afh changed the base branch from master to feature/i18n April 25, 2023 05:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Prepare for language translations #2242

Prepare for language translations #2242

afh commented Apr 16, 2023 •

edited

afh Apr 16, 2023

afh Apr 16, 2023 •

edited

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023 •

edited

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023

afh Apr 16, 2023

	throw_(runtime_error, _f("%1%: %2%") % err.source() % err.asString());
	throw_(runtime_error, _f("Unable to initalize GPG at %1%: %2%") % err.source() % err.asString());

	set(GETTEXT_LOCALE_DIR "FIXME")
	set(GETTEXT_LOCALE_DIR "locale")

Prepare for language translations #2242

Are you sure you want to change the base?

Prepare for language translations #2242

Conversation

afh commented Apr 16, 2023 • edited

TODO:

Choose a reason for hiding this comment

afh Apr 16, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

afh Apr 16, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

afh commented Apr 16, 2023 •

edited

afh Apr 16, 2023 •

edited

afh Apr 16, 2023 •

edited