st-tech / st-tech/ppf-contact-solver

[Feature] Centralized UI localization

Open
#97 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

deployed enhancement worked
Dominant language
Python
Stars
4.5k
Forks
334
PR merge metrics
No merged PRs in 30d

Description

Motivation

The add-on has all display text hardcoded in English across the panels, operators, and property definitions, with no infrastructure for translation. Community members have started offering to translate and proofread the UI into their own languages, but there is nowhere for that work to land. Adding a centralized localization layer lets contributors supply translations for any language without touching Python, and gives non-English users a UI in their own language.

Proposal

Adopt Blender's native bpy.app.translations system with a single centralized catalog per language:

  • Add a blender_addon/i18n/ package holding one catalog file per locale (e.g. ko_KR.json, ja_JP.json) keyed by the English source string, plus an en.json master list of all keys.
  • i18n/__init__.py loads the catalogs, builds the {locale: {(context, msgid): msgstr}} dict, and calls bpy.app.translations.register(__package__, ...) from the add-on's register() (and unregister on teardown).
  • Static text (bl_label, property name=/description=, enum labels, layout.label/operator text=) is translated automatically once the user enables Preferences > Interface > Translation.
  • Dynamic strings (mainly self.report(...) and computed labels) get wrapped with pgettext_iface / pgettext_tip, preserving {} placeholders. This is the bulk of the manual work and can land incrementally.
  • Translators edit only the catalog files, so a language contribution stays language-only with no code review needed for the strings themselves.

Adding a new language is dropping in one catalog file, no code changes. Scope covers add-on UI only; console logs, README, and docs stay English.

Alternatives Considered
  • gettext .po/.mo catalogs like Blender core: standard and tooling-friendly, but heavier setup than one add-on needs. JSON catalogs can be exported to PO later if Weblate/POEditor is wanted.
  • A homegrown draw-time string-replacement layer: reinvents bpy.app.translations and would miss tooltips and enum labels, so rejected.
Additional Context

Translatable surface in blender_addon/: roughly 153 bl_label, 274 property name=, 195 draw-time label/operator text=, 38 enum lists, and about 251 self.report strings. Blender's built-in "Manage UI translations" (ui_translate) add-on can export the add-on's messages to PO to seed the catalogs.

Contribution Agreement
  • I confirm that any code, patches, scripts, attachments, or other copyrightable material I include in this issue may be used, reproduced, modified, and distributed by this project under the Apache License 2.0 or as otherwise described in CONTRIBUTING.md.
  • This is a feature request from the community (please provide a reference below).
Community Reference

https://github.com/st-tech/ppf-contact-solver/discussions/94

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by inspecting the existing blender_addon/ UI code and the proposed blender_addon/i18n/ package boundary, then read Blender's bpy.app.translations documentation and the add-on register/unregister entry points. Inventory the static and dynamic strings described in the issue, and verify how the translation catalog structure handles contexts and {} placeholders. Done means catalogs can be registered and removed cleanly, static and wrapped dynamic UI text translate, and translators can add a locale without code changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
internationalization
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.