Local Overrides for Translations

[dsblank]

Summary

Gramps gets all of its user-visible text — menus, dialogs, calendar month
names, everything — from a translation system, filled in by volunteer
translators for each of the 58+ languages Gramps supports. Today, that
system is entirely one-directional and entirely tied to whatever shipped in
the last release: an individual user has no way to adjust a single word to
their own preference, and the app has no way to benefit from a translation
fix a volunteer made yesterday until the next full Gramps version ships,
months later.

Local Overrides for Translations is a general capability that removes
both restrictions, in three related ways:

1. Personal overrides — any user can replace any specific piece of
   Gramps' text with their own preferred wording, permanently, without
   touching the installed application. This allows users to directly
   override specific words or phrases for a highly flexible approach for
   handling deep dialectal, regional, or personal vocabulary preferences.
2. Pulling updates from Weblate — Gramps can check the community
   translation platform (Weblate) for fixes made since the user's
   installed version was released, and apply them locally, ahead of the
   next full release.
3. Pushing overrides to Weblate — a translator who notices and fixes a
   problem while actually using Gramps can contribute that fix back
   upstream directly, without a separate trip to the Weblate website. This
   is a new, lower-friction workflow for the volunteer translators who
   maintain Gramps' language support today.

All three are built on the same small mechanism: a local, personal
translation entry that Gramps checks before falling back to whatever
shipped. The difference between the three is only where the entry came
from and where it's allowed to go — not how it works.

Why it matters

• For end users: a genuine, permanent fix for the "I don't like this
  one word" problem — which turns out to affect far more than the Hebrew
  calendar spelling that motivated this project (see "Origin," below).
  Nothing about it is calendar-specific; it works for any translatable text
  in the entire application.
• For everyone running a non-English build: translation quality no
  longer has to wait for a release cycle. Community fixes on Weblate can
  reach users within days instead of months.
• For volunteer translators: today, fixing a Gramps translation means
  noticing a problem while using the app, then separately opening the
  Weblate website, finding the same string again, and fixing it there. This
  collapses that into one step — fix it where you saw it, optionally push
  it upstream immediately — which should make it easier to keep Gramps'
  many translations healthy over time.

Architecture: one mechanism, three uses

The shared foundation: intercepting translation lookups

Every time Gramps needs a piece of text, it asks the translation system
"what's the text for X, in the current language?" The override mechanism
adds one check before that: "is there a local override for X? If so, use
it instead." An override entry looks like this:

{
  "language": "en",
  "context": "Hebrew month lexeme",
  "msgid": "Nisan",
  "msgstr": "Nissan"
}

— language, the original English phrase (msgid), a disambiguating
context where needed, and the replacement text (msgstr). This is
deliberately the same shape a translation takes anywhere else in Gramps
(and the same shape Weblate itself uses internally), so an entry can move
between "something a user typed locally," "something pulled from Weblate,"
and "something pushed to Weblate" without any translation or reformatting.

Entries are always tied to a specific language, matching how translation
already works — the same English phrase gets an independent replacement
per language, so one user's preference never bleeds into another
language's experience.

One useful side effect of Gramps' architecture: the same lookup is used
both to display text (turning a stored value into the words you read)
and to understand text you type back in (e.g. turning "Nissan," typed
into a date field, back into the correct month). Because the override
check sits at that one shared point, a single entry fixes both directions
automatically, with no separate work required for user input.

This core mechanism has already been built and directly verified against
the running application: overriding a word changed both what Gramps
displayed and what it accepted as typed input, confirming the basic
approach works, not just in theory.

Mode 1 — Personal overrides

A user keeps a small file, custom_translations.json, in their personal
Gramps settings folder — not inside the installed program, so a Gramps
upgrade never touches or overwrites it. Anything in this file is private by
default: it's the user's own permanent choice, and nothing about it is ever
sent anywhere automatically.

Mode 2 — Pulling updates from Weblate

Every installed translation file already records, internally, the date it
was last revised. Using that as a starting point, Gramps can ask Weblate,
for the user's language, "what's changed since then?" and get back just
the differences — typo fixes, improved wording, anything the community has
done since the release the user is running. Accepted updates are kept in a
second file, weblate_translation_updates.json, separate from personal
overrides, entirely disposable, and only ever fetched when the user
explicitly asks Gramps to check.

Mode 3 — Pushing overrides to Weblate (new)

A translator working in their own language may notice, in the course of
normal use, that a translation is wrong or could read better. Today,
fixing that means leaving Gramps, finding the same string on the Weblate
website, and fixing it there. With this architecture in place, the same
override entry the user would create locally can, if they choose, also be
submitted to Weblate as a real suggestion — using Weblate's own web API,
authenticated as that translator's Weblate account.

This is opt-in per entry, not automatic: a personal override is private
until the user deliberately asks to contribute it, since not every local
tweak someone tries is meant to become the official translation for
everyone. The authentication and submission flow for this direction is not
yet designed in detail — it's included here because the architecture
already supports it naturally (an override entry already looks exactly
like what Weblate expects to receive), and it's a meaningful new workflow
worth building toward, not just a byproduct.

Finding the right phrase to override

Knowing the mechanism exists is one thing; knowing exactly which English
phrase to target is another — Gramps has roughly 7,600 distinct
translatable phrases, far too many to expect a user to already know by
heart. Two complementary sources solve this:

• A complete offline catalog, shipped with Gramps. Gramps' own build
  process already extracts every translatable phrase into a template file
  as the first step of producing translations at all. Reusing that same
  file to ship a small, searchable, offline index — rebuilt automatically
  every release — means finding a phrase to override never depends on
  being online. This is the reliable fallback the whole feature stands on.
• Weblate, for live search and current translations. Because Weblate
  already exposes its data through a public web API, Gramps can search
  across every string in the app and see the current official
  translation for any language — not just the one the user happens to be
  running — live, on request.

Both are used only when the user actively searches or checks for updates;
neither runs automatically in the background (Weblate's public API has a
modest daily request limit for anonymous use, which reinforces this as the
right design regardless).

Keeping the three kinds of entries straight

It matters that personal choices, pulled updates, and pushed contributions
don't get tangled together:

• A personal override is deliberate and permanent, and private unless
  the user explicitly chooses to contribute it upstream.
• A pulled update is the community's own fix, worth having early but
  entirely disposable — safe to re-fetch or discard at any time, since it's
  just a local mirror of something that will show up in the next release
  regardless.
• A pushed contribution is a personal override the user has
  specifically flagged to share, not the default fate of every override.

Personal overrides and pulled updates live in two separate local files, and
when both apply to the same phrase, the user's own personal choice always
wins — a deliberate customization should never be silently overwritten by
an incoming community fix.

How it all fits together

flowchart TD
    subgraph Local["On the user's machine"]
        P[custom_translations.json\npersonal overrides]
        U[weblate_translation_updates.json\npulled community fixes]
    end

    T[Gramps needs to display or\nunderstand a piece of text] --> B{Personal override\nexists?}
    B -- yes --> R[Use it]
    B -- no --> D{Pulled update\nexists?}
    D -- yes --> R
    D -- no --> S[Use the normal shipped translation]

    P --> B
    U --> D

    OC[Offline phrase catalog\nshipped with Gramps] -.helps find phrase.-> Edit[Editor: search & override]
    WS[Live search via Weblate] -.helps find phrase.-> Edit
    Edit -- save --> P

    WC[Check Weblate for updates\nsince last revision date] --> U

    P -- user opts in --> Push[Submit to Weblate\nas a suggestion]

Loading

Origin

This project started from a specific, narrow request: a user wanted to
change the spelling of Hebrew calendar month names (Nisan → Nissan,
Heshvan → Cheshvan) in the English build of Gramps, and discovered
there was no way to do it — English is the untranslated source language,
so there's no translation file to edit for it. A few heavier fixes were
considered and set aside along the way: adding a whole new "language" for
customization (raises the question of what covers everything not
customized), a new plugin category specific to calendars (solves only
calendars), and editing installed translation files directly (gets wiped
out by every upgrade). The mechanism described above is what those
explorations converged on — and it turned out to generalize well past the
original request, into the three-mode capability described here.

Status

• Built and verified: the core override mechanism (Mode 1's
  foundation) — confirmed, against the real running application, that a
  local override correctly changes both displayed text and what Gramps
  accepts as typed input.
• Designed, not yet built: the offline phrase catalog; Weblate-backed
  search; pulling updates from Weblate (Mode 2); the editor UI a user would
  use to search for a phrase and enter an override.
• Identified, not yet designed in detail: pushing contributions to
  Weblate (Mode 3) — the authentication and submission flow for this
  direction still needs to be worked out.

[hgohel]

@dsblank I'm not sure I've seen this work that way you're proposing; might be a cool innovation!

Goals 2 & 3, by which translations reach non-English users faster, and give translators an easy way to update translations respectively, are wins. I can see that end-users may feel the urge to update Gramps' built-in translations when they are incorrect, but with the example provided (i.e. Nisan/Nissan) I am wondering if this is a variant that might be added to Gramps for wide-spread use, or a truly a personal preference?

Anyway, my general concern is similar to one I mentioned in a related discussion, i.e. there should be sufficient checks in place to avoid situations where an incompatible translation update (if it is forced/automatic) would cause a loss of functionality with an older version of Gramps. In case of Gramps, infrequent releases with string changes make this less likely than with addons. However the concern remains, although it may be that I don't understand the mechanism fully so let me know if it doesn't apply in this case.

[Nick-Hall]

but with the example provided (i.e. Nisan/Nissan) I am wondering if this is a variant that might be added to Gramps for wide-spread use, or a truly a personal preference?

There doesn't appear to be a standard transliteration of the Hebrew alphabet into English, so there may be a need for a preference in this case.

Anyway, my general concern is similar to one I mentioned in a related discussion, i.e. there should be sufficient checks in place to avoid situations where an incompatible translation update (if it is forced/automatic) would cause a loss of functionality with an older version of Gramps.

A common error in translation is with python format strings which could cause Gramps to crash. We have warnings in Weblate and also in our release process to prevent this.

[hgohel]

Anyway, my general concern is similar to one I mentioned in a related discussion, i.e. there should be sufficient checks in place to avoid situations where an incompatible translation update (if it is forced/automatic) would cause a loss of functionality with an older version of Gramps.

A common error in translation is with python format strings which could cause Gramps to crash. We have warnings in Weblate and also in our release process to prevent this.

@Nick-Hall The situation I am thinking of is that a user is on Gramps 6.x which supports this feature and chooses not to upgrade even when Gramps has moved to 7.x and translations have changed. Automatic/forced update (if they occur) cause an incompatible translation to be downloaded and cause a problem with the user's installation.
If I understand your response, that prevents bad strings from going in; does it cover the case where the translation is correct, but it is incompatible with a string from a prior release?

[Nick-Hall]

No. My comment an additional concern.

[dsblank]

For goal 1, allowing users to directly override specific words or phrases allows a highly flexible approach for handling deep dialectal, regional, or personal vocabulary preferences. This is just a display preference for most of the 7,600 strings (still great for individual usability). But for dates it is an important ability to be more flexible in the workflow (eg, entering dates).

Of course we will provide strong checks to prevent any crashes or misconfigurations.

Regarding using gramps version 6 when weblates moves on to gramps 7, there is no forced or automatic upgrade. But if a user did upgrade translations, they are still tied to a specific message id. If that message id changes (say to use multiple formatted words) this shouldn't cause a problem.

Is there a situation that could cause an issue that I am not thinking of?

[hgohel]

@dsblank

... This is just a display preference for most of the 7,600 strings (still great for individual usability). But for dates it is an important ability to be more flexible in the workflow (eg, entering dates).

This framing makes it easier to see how more Gramps users might use it even if they don't think the current Gramps translation is wrong per se.

Regarding using gramps version 6 when weblates moves on to gramps 7, there is no forced or automatic upgrade. But if a user did upgrade translations, they are still tied to a specific message id. If that message id changes (say to use multiple formatted words) this shouldn't cause a problem.

Is there a situation that could cause an issue that I am not thinking of?

Here's an hypothetical: Gramps v6 has a string which has only one parameter substitution. Gramps v7 changes the code so that the string now has an additional parameter. An update of the strings may cause a problem with an older version which doesn't provide two parameters. What would happen?

Perhaps the msgid would change so the new string would not be attempted to be used, but if the previous msgid would not be present in the new strings, wouldn't that cause a problem?

[Nick-Hall]

The new string with the extra paramater would have a new msgid by definition.

[dsblank]

This framing makes it easier to see how more Gramps users might use it even if they don't think the current Gramps translation is wrong per se.

Thanks: I updated the project description to include this phrasing.

[dsblank]

Idea: automated pseudo-localization testing to catch overlooked non-translated text

While testing the override mechanism from PR #2483, I generated a full-catalog override that transforms every string in gramps.pot (~7,600 entries) into Pig Latin — a standard "pseudo-localization" QA technique (the same idea behind Mozilla's/Microsoft's pseudo-locale builds), not a real language. It's purely algorithmic (move the leading consonant cluster to the end + "ay"), so it has zero vocabulary gaps and is trivial to verify by eye. Installing it as a personal override and running Gramps normally made it immediately obvious which UI text was and wasn't actually reaching translation.

That surfaced a real gap: most menu items and a lot of static dialog text — anything defined via GtkBuilder XML with translatable="yes" (.glade files, and the inline menu XML in grampsgui.py) — never reached the override, because Gtk.Builder translates that text internally via GLib's C-level dgettext(), bypassing Gramps' Python translation object entirely.

This suggests a cheap, ongoing regression test built on the same idea: load every .glade file (and the main menu XML) with a Pig Latin (or similar algorithmic pseudo-locale) active, walk the resulting widget tree, and fail if any label/tooltip/button text still reads as plain English. That's a strong signal a string isn't wrapped in _() (or marked translatable="yes") at all, or otherwise isn't reaching the catalog — exactly the class of bug found above.

Scope/tradeoffs worth noting:

• Static .glade files and menu XML are cheap to walk exhaustively; dialogs that build labels imperatively in Python at runtime would need the UI actually driven to reach them, which is a bigger lift.
• It would need a small allowlist for legitimate non-translatable text (proper nouns, file extensions, format codes) to avoid false positives.
• Even the narrow scope (just .glade + menu XML) would catch this exact class of bug automatically on every CI run, instead of only when someone happens to eyeball a pseudo-localized build.