RFC: Redesigning the L10n Architecture for Gramps Addons

[bryndin]

RFC: Redesigning the L10n Architecture for Gramps Addons

Status: Proposed
Reviewers: @Nick-Hall @eduralph @GaryGriffin
Subject: Decoupling Gramps Addon localization from addon releases

1. Abstract

This RFC defines a decoupled architecture for Gramps Addon localization. The current workflow couples translation updates to addon releases, requiring manual maintainer intervention and delaying translation improvements for users. By treating localization as independent content delivered over-the-air (OTA), translation updates become independent of addon code releases. This reduces maintainer effort, simplifies repository management, and ensures runtime safety through validated localization artifacts.

2. Motivation

The current localization workflow utilizes a centralized translation platform (Weblate) but relies on a decentralized, manual distribution pipeline. This creates several bottlenecks:

• Maintainer Burden: Maintainers must manually pull from Weblate, run extraction scripts (make.py extract-po), and bundle .mo files into .tgz release archives.

• Release Coupling: A typo fix in a translation requires a full version bump and release of the addon code.

• Repository Pollution: Mixing source code with .po translation data confuses contributors and bloats the git history of addons-source.

• Fragility: A malformed translation string (e.g., mismatched %s variables) can crash the Gramps client if not caught manually.

• Contributor burden: Translation details distract contributors from addon development.

This RFC decouples localization from addon development and release management, enabling automated translation delivery while preserving compatibility with the existing GNU gettext ecosystem.

3. L10n Architecture

The localization system is composed of several independent components. Each component has a single responsibility and communicates with the others through well-defined interfaces.

The architecture does not prescribe how these components are implemented or where they are hosted. The concrete implementation is described later in the Reference Implementation section.

3.1 Architectural Principles

The redesign is based on the following principles.

• Localization is managed independently from addon releases.
• Translation source data is managed independently from addon source code.
• Translation updates are optional and can be delivered independently.
• Invalid translations must never compromise application stability.
• Components communicate through stable contracts rather than implementation-specific mechanisms.
• Local translation testing is deprecated in the standard toolchain. Addon developers are responsible only for US English strings in their code. If developers wish to test UI layouts with other languages locally, they must manually compile dummy .mo files using standard gettext tools.

3.2 System Components

Extractor

Extracts translatable strings from the source code files and produces translation templates.
The extractor is triggered whenever the source code changes.

Source (aka Translator)

Provides the user interface where translators create and maintain translations.

The translation source is responsible only for authoring translations. It has no responsibility for packaging or distributing them.

Repository

Stores translation source files independently of addon source code.

It is the authoritative source for localization data and provides the input for translation builds.

Builder

Transforms translation source files into runtime artifacts suitable for distribution.

The builder is responsible for validating translations before publication.

It guarantees that invalid translations cannot prevent valid translations from being published and cannot reach end users.

Registry

Publishes information about available localization artifacts.

The registry allows clients to discover available translations, determine whether updates exist, and retrieve the metadata required to validate downloaded artifacts.

The registry is implementation-independent. Multiple registries may coexist.

Manager

A client-side subsystem responsible for discovering, downloading, validating, caching, and loading localization artifacts.

It presents translations to the runtime through the standard gettext interface and is independent of the underlying distribution mechanism.

Resolver

Runtime logic used in the source code, responsible for loading and applying the correct translations.

4. Architectural Invariants

The following properties are required regardless of implementation.

4.1 Text Domain Isolation

Each addon owns an independent gettext text domain. Translation catalogs are never shared between addons.

4.2 Independent Versioning

Localization artifacts are versioned independently of addon releases. Updating translations does not require publishing a new addon version.

4.3 Failure Isolation

Invalid translations must never:

• prevent valid translations from being published,
• prevent localization updates for unrelated addons,
• compromise application stability.

When validation fails, clients must safely fall back to English source strings.

4.4 Atomic Updates

Localization updates must be installed atomically. Clients must never observe partially installed translation data.

4.5 Multiple Translation Providers

The architecture supports multiple translation registries. If multiple registries provide translations for the same addon, the end-user defines the deterministic precedence ordering.

5. Runtime Model

The client maintains a local cache of installed localization artifacts.

When the source code initializes translations, the Resolver resolves directories using the following precedence:

1. locally installed localization artifacts
2. translations bundled with the addon
3. English source strings

Localization artifacts are downloaded, validated, and installed atomically.

The runtime always prefers newer localization artifacts while preserving compatibility with bundled translations.

6. Security Considerations

The OTA payload relies on SHA-256 hashing to ensure network transit integrity. Preventing supply-chain attacks via cryptographic signing (e.g., GPG) is considered Out of Scope for this RFC, as it should be handled holistically by the Gramps project for all plugin downloads in the future.

7. Migration Strategy

Migration can be performed incrementally.

1. Introduce the new localization architecture while preserving the existing workflow.
2. Deploy the Builder and Manager.
3. Publish localization artifacts independently of addon releases.
4. Deprecate bundled translation catalogs once all supported versions understand the new architecture.

This approach allows existing code to continue functioning throughout the transition.

8. Reference Implementation

This section describes the planned implementation for the Gramps project.

8.1 L10n Paths

Since the plugin update overwrites the plugin directory, we have to decouple the source code from the translations.

• Plugins: ~/.gramps/gramps60/plugins/<plugin-name> (and its equivalents on Windows and macOS), as they were before.
• OTA translations: ~/.gramps/gramps60/plugins_locale/<plugin-name>.

If we later decide to decouple Gramps Core translations from its releases, ~/.gramps/gramps60/locale/ will work similarly.

8.2 Server-Side Infrastructure

• Extractor will reuse the existing make.py init and aggregate-pot stages. The GitHub Action checks out both addons-source and the Gramps Core gramps repository, allowing aggregate-pot to remove strings already translated by Gramps Core. It generates both the individual addon template.pot files and the aggregated translation template. When a PR merges into addons-source, the workflow commits the updated templates into the addons-translations repository. See the Repository Ownership section below.

• Repository: To preserve a Git-backed source of truth for disaster recovery while keeping code history clean, a new repository (addons-translations) will be created.

• Artifact Generation: A nightly Builder GitHub Actions cron job pulls the latest translation repository. It first reconstructs per-addon translation catalogs by matching the aggregated translations against each addon's template.pot. After validation, it compiles per-addon .mo files and packages them into {addon}_l10n.tgz archives. These archives contain only the locale/ directory structure. See Translation Catalog Organization for the the artifiact storage opions.

  • The Builder script must reject the entire language file for an addon if the Plural-Forms headers are invalid. This prevents the compiler from generating structurally corrupted .mo files that could crash the client.
  • Optionally: Use polib to prune per-entry offending entries.

• Binary Hosting (GitHub Releases): To prevent git history bloat, the generated .tgz files are attached to a continuous, rolling tag (e.g., l10n-gramps60-latest) via GitHub Releases. We store only the latest build.

• The Registry (l10n_index.json): A static manifest file is generated and hosted on gh-pages. This acts as a fast, highly-available index for the Gramps client to check for updates.

  • Conditional GET: the index is one monolithic JSON for all addons; use ETag/If-None-Match (gh-pages supports it) to avoid refetching unchanged.

• Test Isolation: L10n formatting tests reside strictly within this new CI pipeline. Standard python/UI tests remain in addons-source.

Repository Ownership

Because both the automated Extractor (pushing .pot files) and Weblate (pushing .po files) will write to the addons-translations repository, strict ownership and concurrency controls are required to prevent Git tree conflicts and Weblate merge locks.

The implementation may choose one of the following strategies.

Option A (preferred): Branch Isolation

The Extractor commits generated translation templates to a dedicated branch. Weblate maintains translations on its own working branch. The Builder combines the required inputs during the build process. Automated systems must never modify another system's working branch or perform force-pushes to it.

Option B: Pull Request Workflow

Instead of committing directly, the Extractor opens PR containing updated translation templates. Weblate remains the sole automated writer of the primary translation branch. Translation updates are incorporated through the normal review and merge process.

Translation Catalog Organization

The implementation requires both aggregated translations for efficient translation authoring and per-addon catalogs for runtime distribution.

Option A (preferred): Per-addon + Aggregate

The Extractor generates both the individual addon template.pot files and an aggregated translation template. Translators work with the aggregated catalog, while the Builder reconstructs per-addon catalogs by matching the aggregated translations against each addon's template.pot before compiling the runtime .mo files.

This approach keeps the Builder self-contained while preserving the current translation workflow.

Option B: Weblate handles per-Addon Translation Sources

Instead of maintaining a single aggregated translation catalog, the Repository stores independent translation catalogs for each addon. The Builder compiles these catalogs directly into the corresponding runtime artifacts without requiring a reconstruction step.

This approach simplifies the build pipeline at the cost of increased repository organization and translation management complexity.

8.3 Client-Side Resolution

• Fetch & Hash Check: The Gramps Addon Manager periodically (using its existing schedule functionality) fetches l10n_index.json. It iterates through installed addons and compares the remote latest_hash against a locally stored hash.

• Global Extraction: If an l10n update exists, the client downloads the .tgz and extracts it into a global user directory: ~/.gramps/gramps60/plugins_locale/.

  • Atomicity requirement: To prevent Gramps from freezing or displaying broken UI states due to partially extracted files, the client must:
    1. Download the archive to a temporary directory inside ~/.gramps/gramps60/tmp (same filesystem).
    2. Verify the checksum of the downloaded payload against the latest_hash in the Registry.
    3. os.replace() each .mo file individually into place. Each file swap is atomic; crash mid-loop leaves some languages new and some old, which is fine — they're independent domains.
    4. Clean up the temporary directory.

• Path Injection (gettext): Gramps Core's initialization logic GRAMPS_LOCALE (the Resolver) will be modified. We have two options:

  • Option A: by utilizing gettext.bindtextdomain to follow Runtime Model and try ~/.gramps/gramps60/plugins_locale/, the OTA translations natively take precedence over any legacy locale/ directories bundled within the addon itself.

  • Option B (preferred): have a per-message fallback via

    t = gettext.translation(domain, OTA_DIR, [lang], fallback=True)   # NullTranslations if absent
    t.add_fallback(gettext.translation(domain, BUNDLED_DIR, [lang], fallback=True))
    # lookup: OTA catalog → bundled catalog → NullTranslations → original English msgid

• Manager uninstall lifecycle:

  • Uninstall: If a user uninstalls an addon, the Addon Manager must wipe its corresponding translations from the OTA cache to save space.
  • Disable: If an addon is merely disabled, its translations should remain cached.

• Manager: handles the network fetch itself. The Addon Manager's fetch logic must gracefully handle offline states, CDN outages, and rate limits without throwing user-facing errors, silently failing back to the previously cached .mo files or legacy bundled translations.

• During the migration phase, the Resolver will fall back to legacy bundled .mo files. Post-migration, when addons no longer bundle translations, an offline or failed OTA fetch will simply result in the addon rendering its hardcoded English source strings.

• Extractor cleanup: Post migration, we will change to the existing make.py do_tar logic. The packaging script will be configured to cease bundling the local locale/ directories into the primary addon .tgz files.

8.4 Translation Registry

The registry is implemented as a static JSON document generated by the build pipeline. It is published as static content.

The schema:

{
  "schema_version": 1,
  "gramps_target": "6.0",
  "addons": {
    "CardView": {
      "latest_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "timestamp": "2023-10-27T10:00:00Z",
      "source_revision": "abc123d4e5f6...",
      "archive_url": "https://cdn.example.com/CardView_l10n.tgz",
      "languages": ["en", "es", "fr"]
    }
  }
}

• schema_version: the Registry schema version. A placeholder in case we will need to change it in the future.
• gramps_target: the Gramps version that the translations are compatible with.
• latest_hash: the SHA-256 checksum of the .tgz payload.
• timestamp: Formatted in RFC3339 UTC.
• source_revision: The exact Git commit hash from the Repository used to generate the build, ensuring traceability.
• archive_url: The URL to the .tgz payload.
• languages: The list of languages supported by the addon, so the client can skip downloading an artifact that lacks the user's language.

9. Known Limitations

Users who don't update addon code

User runs CardView v1.0 (code contains msgid "Foo"). CardView v1.1 renames "Foo"→"Foobar", translators localize it, Builder ships the latest artifact whose .mo now contains only "Foobar". The non-updating user's v1.0 code requests "Foo" → OTA .mo lacks it → English, losing a translation they previously had.

Option A: (preferred) Users refusing an update are on their own.

• If an addon contributor breaks the next version, it's their responsibility to fix it and fall forward.
• The same hold for preserving addon functionality.

This is a rare case not worth the overengineering. With the Client-Side Resolution Path Injection, the users can update translations locally for themselves.

Option B: Don't deprecate the pipeline bundling translations with the addons. Addon contributors can customize their translations.

The extra complexity of two concurrent pipelines is confusing and more bug-prone. Translations are a nuance, not a blocker.

Option C: Develop the addon <-> translation version. Store all the translation versions. Manager is responsible for matching.
Significantly complicates the solution and requires extra storage space, for the corner case benefits. It's overengineering.

Appendix

Compatibility of the Latest-Only Model

This architecture distributes only the latest localization artifact for each addon. Translation artifacts are not versioned alongside addon releases.

This model is compatible with the way gettext resolves translations.

Change	Result
A string is removed	Older translations simply contain an unused entry.
A string is added	Older addon versions never request the new string.
A source string changes	The lookup key changes and the runtime falls back to the English source string.
A translation context changes	The lookup key changes and the runtime falls back to the English source string.
A translation is invalid	The Translation Builder excludes invalid data before publication.
An addon no longer contains a translated string	The runtime no longer requests that translation.

As a result, translation updates remain backward compatible without requiring localization artifacts to be tied to specific addon versions.

Gramps Addons - Current l10n process

Gramps Addons - Current l10n process

[eduralph]

@bryndin - here are some thoughts on your suggestion, not in any important order

• The fallback from addon to Gramps - if a translation item already exists in Gramps you do not have to include it in the addon. This is driven by the point that the community covers translations and we want to ensure they can reuse as much work as possible
• The github action - would be a great addition to the PR 820 - CI, which is in the pipe
• You might want to post it on discours as much of the contributing participants can be found there

[bryndin]

Thanks for the feedback

• The fallback from addon to Gramps - if a translation item already exists in Gramps you do not have to include it in the addon. This is driven by the point that the community covers translations and we want to ensure they can reuse as much work as possible

My understanding aggregate-pot part of main.py handles the string removal and it requires gramps repo.

• The github action - would be a great addition to the PR 820 - CI, which is in the pipe

Yes, I'd love to see more things automated and take the load off @GaryGriffin.

• You might want to post it on discours as much of the contributing participants can be found there

What's "discours"? Can you share the link? I don't know how the processes work in the project.

[eduralph]

What's "discours"? Can you share the link? I don't know how the processes work in the project.

https://gramps.discourse.group/c/gramps-development/

That's where a lot of the conversation around development happens.

[kulath]

@bryndin Could you please add a section right at the start of this PR, describing what problem this PR is trying to solve.

(I am not in any way trying to criticise this change, just want to make sure that the purpose is clearly understood).

I noticed that when I published my CensusCheck addon gramps-project/addons-source#814, the template.pot that @GaryGriffin was working on was for Gramps 6.1, although the current Gramps was 6.0. Even if the template was for 6.0, translations would only happen after publication of the addon, so there was no chance that translations could get picked up if the addon was downloaded by a user immediately. I suppose this might be the problem you are trying to solve, but I'm not sure, and a clearer explanation (clearer than the rather rushed one I am typing now) would be enormously helpful.

[bryndin]

@bryndin Could you please add a section right at the start of this PR, describing what problem this PR is trying to solve.

Good catch! We started the original discussion in my addon PR thread, and I forgot to include the "Motivation" section. It's added now.

I noticed that when I published my CensusCheck addon gramps-project/addons-source#814, the template.pot that @GaryGriffin was working on was for Gramps 6.1, although the current Gramps was 6.0. Even if the template was for 6.0, translations would only happen after publication of the addon, so there was no chance that translations could get picked up if the addon was downloaded by a user immediately. I suppose this might be the problem you are trying to solve, but I'm not sure, and a clearer explanation (clearer than the rather rushed one I am typing now) would be enormously helpful.

Ideally, all that translation burden (except the use of gettext inside addons) will be off the contributors' radar.

[bryndin]

@eduralph @GaryGriffin @Nick-Hall

I registered at discource, but I can't post the link to this RFC there. Getting a bunch of weird errors:

• First, an error about "not having access to a resource", when I tried to post the link to this github discussion and 2 paragraphs of the RFC. No idea what it means. So, I tried multiple times removing the link, removing the markdown paragraphs, and trying again, all with that error.
• Now I'm getting: An error occurred: Access Denied

Update: Apparently, my account there is on hold. This is an automated message from The Gramps Project (Discourse Forum & Mailing List) to let you know that your account has been temporarily placed on hold as a precautionary measure.

To be honest, I'd prefer to spend more time on RFCs and code, than fighting the signup systems, getting approvals, and getting help around the bugs in these systems. By now, I have 4 (four) separate accounts in Github, Gramps bugtracker, Gramps Wiki (not working, bugged out signup), and Gramps Discourse (got approval, but banned now). It might help to review the contributor processes to decrease the friction, as it's not very productive. #letthebuidersbuild.

[eduralph]

I get where you're coming from. I wish my GEPS had already been decided on, but the teams bandwidth has limits and there are priorities. Especially at the beginning one sees so many possibilities and really want to move things. It's really worth taking the time to have the conversation - you can really get some insights to make things better.

[emyoulation]

Discourse automated moderation is suspicious of new users who 'paste' their first postings. It assumes that means a 'bot is spamming the forum and 'silences' them. Then a human moderator has to override. Sorry that I did not recognize your user name and left it for Nick. (Although if something more than a username was filled in on the form... like OS or Gramps version... then I would not have hesitated.) Unfortunately, when Discourse silences because of "typed too fast", it does not show the draft to the moderator.

Nick has upgraded your account (2 steps) from "New User" to "Member". Looking forward to seeing your posting.

[hgohel]

@bryndin Based on an initial review of the RFC -

1. Not having worked on addon translations, I am curious to hear from addon developers and particularly @GaryGriffin as to how this would help him as maintainer. I don't have any idea of how much of a burden the current system is for maintainers, developers or addon users at the moment.
2. I like that translations are updated periodically, but I am concerned about this: "Users refusing an update are on their own." The fact that this new system could leave user's addon in a broken translation state is a problem being introduced. Is there a reasonable way to prevent this? For example, if the addon version isn't the latest, then don't upgrade translations? I understand that's not ideal, so perhaps other solutions can be discussed.
3. Re: "Addon developers are responsible only for US English strings in their code." Does this work for non English-speaking addon developers? Perhaps it does because this is how it might be today as well?

[bryndin]

@hgohel

My view on the system architecture:

• Whatever can be automated and doesn't change often is automated
• Weakly related entities (business logic and translations) are decoupled to be maintainable in the long term
• Contributors concentrate on business logic, not worrying about translations.

2. I like that translations are updated periodically, but I am concerned about this: "Users refusing an update are on their own." The fact that this new system could leave user's addon in a broken translation state is a problem being introduced. Is there a reasonable way to prevent this? For example, if the addon version isn't the latest, then don't upgrade translations? I understand that's not ideal, so perhaps other solutions can be discussed.

First, it's the responsibility of the addon developer to preserve the backward compatibility. We have two cases:

1. A contributor broke their addon. It's their responsibility to fix it, revert the change, or fix the problem and roll forward. This is not the responsibility of a translation system (I covered it in the RFC).
2. Major addon update containing a breaking change.

Second, if a user prefers an older version, she refuses/disables updates for both addons and translations, and lives in peace.
They shouldn't be updating translations while refusing to update the corresponding addon.

By the way, I don't think Gramps really supports addon versioning. In the Addon Manager, you can't specify the older version to install, similar to PIP or other package managers.

So, to answer your question: There are options, but they come with significant tradeoffs, particularly with complexity and storage. And they get into overengineering territory. If we want real versioning, we'd talk about redesigning the Addon Manager as well.

Re: "Addon developers are responsible only for US English strings in their code." Does this work for non English-speaking addon developers? Perhaps it does because this is how it might be today as well?

No, even now, for translations to work properly, they must be in the Gramps global language, which is en_US, AFAIR.

[hgohel]

@GaryGriffin Thanks for sharing your process and thoughts.

@bryndin Your view of the system is sound.

Second, if a user prefers an older version, she refuses/disables updates for both addons and translations, and lives in peace.
They shouldn't be updating translations while refusing to update the corresponding addon.

I might have missed this in the RFC. My understanding was that translations would update periodically (read, automatically) which could put the user's (older) addon version out-of-sync with the translation.

In the new world, would it be possible to disable translation updates? Do you see that as a per-addon setting or global?

[Nick-Hall]

They shouldn't be updating translations while refusing to update the corresponding addon.

I agree.

By the way, I don't think Gramps really supports addon versioning. In the Addon Manager, you can't specify the older version to install, similar to PIP or other package managers.

Correct. The user is generally expected to upgrade when possible.

[eduralph]

@bryndin , @Nick-Hall

By the way, I don't think Gramps really supports addon versioning. In the Addon Manager, you can't specify the older version to install, similar to PIP or other package managers.

That's exactly the corner where my suggestion GEPS 049 comes in: it would disconnect the Gramps versioning from the addon versioning and essentially get it's own.

Nick, I think bryndin and I both came to the addons with the same, basic assumption: that it is a plugin mechanism similar to others we are familiar with and both were stumped when it turned out not to be the case. I think the current state of things are fair - building a plugin interface is not easy - at the same time, I think it should make an effort to align closer with a more typical plugin approach to lower the entry barrier, the benefits of the proposal aside.

[bryndin]

IMO, the #1 problem to solve for Addons is to make them real Python packages. As eduralph said, the current namespace handling is confusing for anyone familiar with Python. Btw, I'm not even sure the plugin API/interface is a blocker there. Must be the Gramps Core change (hard part is to preserve backward compatibility) + easy addon migration.

[GaryGriffin]

Not having worked on addon translations, I am curious to hear from addon developers and particularly @GaryGriffin as to how this would help him as maintainer.

Personally, I dont think the workload as the maintainer should even be considered. I spend negligible time on translation-related work.

I don't have any idea of how much of a burden the current system is for maintainers, developers or addon users at the moment.

I would argue that the burden is on the Weblate user adding translations. The user also has a burden due to lack of recent translation strings for addons that have not been recently published. It is negligible for maintainters, developers.

Right now,

• I merge the Weblate translation strings to Addons once a month on gramps61. I dont do anything on the other branches. This takes less than 1 minute. Previously I was NOT re-releasing all addons on gramps61 when I merge the Weblate updates. I am open to doing this but wonder if the users really want to update every addon monthly. It would add less than a minute to the process for incrementing all addons and publishing. Users would not know if the update were just translation strings or bug fixes. Every gramps61 PR bug fix update includes all of the translations merged at that point.
• I update new strings to Weblate on an as-needed basis for each gramps61 PR that is merged. That adds less than 1 minute per PR.

Current case:

• if the user is running 5.x, new addon versions are rare and no new translations occur.
• if the user is running 6.0, new addon versions are as needed (often) but no new translations going forward.
• if the user is running 6.1, new addons with latest translations when published.

[kulath]

General

AIUI, two proposals would address somewhat similar issues:

• @bryndin RFC: Redesigning the L10n Architecture for Gramps Addons #2462 and https://gramps.discourse.group/t/rfc-redesigning-the-l10n-architecture-for-gramps-addons/9720
• @eduralph GEPS 049: Addon API Versioning and Plugin Lifecycle Background discussion at Discourse thread 9491 and GitHub Discussion #2297. Current review thread for this proposal: GitHub Discussion #2311.

but I think that this proposal is much better, because it does not introduce a very complicated parallel versioning scheme, and instead ensures that the addon version is tied to the Gramps version, through ~/.gramps/gramps60/plugins/<plugin-name>. This means that users who want to retain an older version of Gramps for whatever reason (preference or incompatibility of newer version with their OS) can easily do so.

Gramps update vs steady state

There are two different situations:

• The Gramps version is being upgraded (this happens to be the current situation), for example from Gramps 6.0 to 6.1 (or equally from 5.2 to 6.0). In this case users are using 6.0, but weblate is pointing at 6.1, and no further updates are made to the translation of 6.0. So if someone releases an addon while in this state, translations are never made for that addon.
• The steady state where the current Gramps is 6.0, and weblate is translation 6.0.

I don't think that this proposal helps the upgrade state. This is not a criticism, just a comment, because I think that solving the upgrade state is worth what is probably a big complex fix. (During the upgrade state, no new translations are possible for the old version).

Motivation

The proposal says:

• Release Coupling: A typo fix in a translation requires a full version bump and release of the addon code.

But actually I think the problem is worse than that.

• If a new addon is created in the steady state, then there will be no translations at all for that addon, and even when weblate translations go through the pipeline, to get those translations, a version bump for the addon will be needed.
• Typo fix in translation as you say this would require a version bump; but if the fix is just in one language, then the version bump would apply for all languages, and users who do not use the fixed language will still be offered the update.
• Typo fix in addon This would cause a version bump, but the new text in the addon would only be presented to Weblate at the time the bumped version was published, so no new translations would not be available at that time.
• Even if an addon version is bumped, for a user to get the new version would require them to use the addon manager settings to check for updates and then to select the updates and 'Install Selected Addons'. The default is to never check for updates (and I have never used this feature at all - mostly the addons are OK as I first installed them!).

@GaryGriffin Could you please confirm that this is all correct?

Suggestion of addon manager updates

I suspect that strings in addons (for a given Gramps version) are rarely updated, so I suggest that for a given Gramps version, once a string is extracted and made available to Weblate, that string is never deleted. Because such changes are probably rare, the cost should be small, and it resolves some of the problems for users who want to retain old versions of addons.

I suggest that the addon manager be enhanced to display two checkboxes, one for addon and one for translation, so users can choose to update only the translation, or only the addon, or both.

I suggest that the default for checking for updates be changed to once a week (or once a month), and translations for installed addons be automatically selected, and automatically installed without further user intervention (the progress window could tell users where to access the Addon Manager to turn off this option). Users can of course change this default. I presume that network traffic for this (and so delay) could be quite small using compression. It could be further optimised by only getting translations for languages the user is actually using (is it possible to tell?)

[Nick-Hall]

I suspect that strings in addons (for a given Gramps version) are rarely updated

This should be the case for most addons unless the are new and being actively developed.

[bryndin]

AIUI, two proposals would address somewhat similar issues:
They are planned to be independent of each other. That said, we'd double-check that we aren't creating blockers for each other.

I don't think that this proposal helps the upgrade state. This is not a criticism, just a comment, because I think that solving the upgrade state is worth what is probably a big complex fix. (During the upgrade state, no new translations are possible for the old version).

The RFC doesn't try to solve that case specifically. My goal is to decouple architectures, automate manual tasks, and most importantly, remove extra noise and friction from addon contributors. They must concentrate on functionality, not on i18n and translations.

IMO, dev friction is the P0 problem with addons. Translations per se are P2 at best. There are always English strings to fallback to.
Moreover, I'm not sure Weblate is still a good solution, given LLMs can handle translations within seconds. Even if AI translation is hallucinated, users can report a bug and propose a better translation. It's a nuance, not a blocker.

Switching from Weblate to LLM-based translation removes all the problems with backporting translations, handling older releases etc.

• If a new addon is created in the steady state, then there will be no translations at all for that addon, and even when weblate translations go through the pipeline, to get those translations, a version bump for the addon will be needed.

If there is new data from Weblate, there will be a new translation release, but no addon release is needed. Addon Manager handles them separately. Unless I'm missing what you're saying.

• Typo fix in translation as you say this would require a version bump; but if the fix is just in one language, then the version bump would apply for all languages, and users who do not use the fixed language will still be offered the update.

While Addon Manager can be smart about it, downloading only needed translations. We are getting heavily into overengineering territory, fixing a problem that doesn't exist.
The P0 goal is to simplify contributors' lives and thus get more add-ons. Not to say a few bytes.

• Even if an addon version is bumped, for a user to get the new version would require them to use the addon manager settings to check for updates and then to select the updates and 'Install Selected Addons'. The default is to never check for updates (and I have never used this feature at all - mostly the addons are OK as I first installed them!).

Exactly, no need to solve a non-existent problem. We are removing the translation friction from the addon developers.

I suggest that the addon manager be enhanced to display two checkboxes, one for addon and one for translation, so users can choose to update only the translation, or only the addon, or both.

I'm seeing it as an additional category within the Addon Manager's (AM) "Available Updates" window (that is different from the main AM interface.

I suggest that the default for checking for updates be changed to once a week (or once a month), and translations for installed

Isn't it already "once a week" as a default?

[GaryGriffin]

But actually I think the problem is worse than that.
... 4 points discussed ...
Could you please confirm that this is all correct?

I believe your problem description is correct.

[Nick-Hall]

Translators work with the aggregated catalog, while the Builder reconstructs per-addon catalogs by matching the aggregated translations against each addon's template.pot before compiling the runtime .mo files.

We should also consider the option of keeping the addon translations aggregated. In this way the standard Gramps translator could be used for addons with the main catalog being gramps.mo and the fallback addons.mo.

[bryndin]

Let me just throw this heresy here, since I've already mentioned it among other things:

---

I'm not sure Weblate is still a good solution, given LLMs can handle translations within seconds. Even if AI translation is hallucinated, users can report a bug and propose a better translation. It's a nuance, not a blocker.

Switching from Weblate to LLM-based translation removes all the problems with backporting translations, handling older releases, and so on.

😎👌🔥