st-tech / st-tech/ppf-contact-solver
[Feature] Centralized UI localization
Nobody has claimed this yet.
- 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 anen.jsonmaster list of all keys. i18n/__init__.pyloads the catalogs, builds the{locale: {(context, msgid): msgstr}}dict, and callsbpy.app.translations.register(__package__, ...)from the add-on'sregister()(and unregister on teardown).- Static text (
bl_label, propertyname=/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 withpgettext_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/.mocatalogs 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.translationsand 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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