revue de la doc de bcasl et du cleaner

Author: PyCompiler ARK++

Plugins/Cleaner/__init__.py

@@ -37,6 +37,8 @@
 
 # classe principale du plugin
 class Cleaner(BcPluginBase):
+    __package_dir__ = Path(__file__).parent
+
     def __init__(self):
         super().__init__(META)
         self.cleaned_files = 0
@@ -104,9 +106,16 @@ def on_pre_compile(self, ctx: PreCompileContext):
             log.log_info(cancelled_msg)
 
     def apply_i18n(self, gui, tr: dict[str, str]) -> None:
-        """Apply plugin-local i18n from Plugins/Cleaner/languages/*.json independent of app languages."""
+        """Apply plugin-local i18n from Plugins/Cleaner/languages/*.json independent of app languages.
+        Accepts either a preloaded plugin-local translation dict (preferred) or a generic
+        translation meta with a language code to resolve the plugin-local file.
+        """
         try:
             self._gui = gui
+            # If 'tr' already contains our plugin keys, use it directly (comes from sync_with_global_language)
+            if isinstance(tr, dict) and any(k in tr for k in ("cleaner_title", "cleaner_question", "cleaner_completed")):
+                self._lang_data = tr
+                return
             # Resolve language code preference
             code = None
             try:
@@ -126,7 +135,7 @@ def apply_i18n(self, gui, tr: dict[str, str]) -> None:
             # Fallback
             if not code:
                 code = "en"
-            
+
             # Normalize codes and build robust fallback candidates
             raw = str(code)
             low = raw.lower().replace("_", "-")
@@ -144,7 +153,7 @@ def apply_i18n(self, gui, tr: dict[str, str]) -> None:
                 "zh-cn": "zh-CN",
             }
             mapped = aliases.get(low, raw)
-            
+
             # Candidate order: mapped -> base (before '-') -> exact lower -> exact raw -> 'en'
             candidates = []
             if mapped not in candidates:
@@ -165,14 +174,14 @@ def apply_i18n(self, gui, tr: dict[str, str]) -> None:
                 candidates.append(raw)
             if "en" not in candidates:
                 candidates.append("en")
-            
+
             # Load plugin-local JSON using the first existing candidate
             import importlib.resources as ilr
             import json as _json
-            
+
             pkg = __package__
             lang_data = {}
-            
+
             def _load_lang(c: str) -> bool:
                 nonlocal lang_data
                 try:
@@ -186,15 +195,21 @@ def _load_lang(c: str) -> bool:
                 except Exception:
                     pass
                 return False
-            
+
             for cand in candidates:
                 if _load_lang(cand):
                     break
-            
+
             self._lang_data = lang_data
         except Exception:
             self._lang_data = {}
 
+    def get_package_dir(self) -> Path:
+        try:
+            return Path(__file__).parent
+        except Exception:
+            return Path.cwd()
+
 
 # enregistrement automatique du plugin dans le registre de bcasl
 PLUGIN = Cleaner()

docs/how_to_create_a_BC_plugin.md

@@ -76,22 +76,66 @@ PLUGIN = MyPlugin()
 
 ## 4) Internationalization
 
-- Place JSON translation files under `languages/`
+BCASL supports plugin‑local i18n files and a lightweight synchronization API so your plugin updates its texts automatically when the app language changes or when using the BCASL only_mod Studio.
+
+- Place JSON translation files under `languages/` in your plugin package
 - Always include `en.json` as the fallback
-- Use `apply_i18n(gui, tr)` in your plugin to update UI if any is exposed
+- Implement `apply_i18n(gui, tr)` in your plugin; it will be called with a translation dict
+- Register your plugin instance for i18n so that synchronization can target it
+- Optionally expose your package directory so the sync layer can auto‑discover your languages folder
 
 Example `languages/en.json`:
 ```json
 {
   "_meta": {"code": "en", "name": "English"},
-  "title": "My BC Plugin",
-  "question": "Proceed with pre‑build checks?"
+  "myplugin_title": "My BC Plugin",
+  "myplugin_question": "Proceed with pre‑build checks?"
 }
 ```
 
+Example `__init__.py` snippets:
+```python
+from pathlib import Path
+from Plugins_SDK.GeneralContext.i18n import register_instance
+
+class MyPlugin(BcPluginBase):
+    __package_dir__ = Path(__file__).parent  # helps i18n sync discover languages/
+
+    def apply_i18n(self, gui, tr: dict[str, str]) -> None:
+        # Prefer preloaded plugin-local dict; else resolve by code
+        if tr and any(k in tr for k in ("myplugin_title", "myplugin_question")):
+            self._lang = tr
+        else:
+            code = (tr or {}).get("_meta", {}).get("code", "en")
+            # resolve languages/<code>.json with fallbacks (code-base, en)
+            # ... load into self._lang
+        # update any exposed text
+        # gui elements or log messages can use self._lang.get("myplugin_title", "...")
+
+PLUGIN = MyPlugin()
+
+def bcasl_register(manager):
+    manager.add_plugin(PLUGIN)
+    register_instance(PLUGIN.meta.id, PLUGIN)  # enable i18n synchronization
+```
+
+Synchronization helpers available:
+- `apply_translations(gui, tr)`: broadcast a translation dict to all registered plugins (used by only_mod Studio)
+- `sync_with_global_language(gui)`: load each registered plugin’s `languages/<code>.json` based on the global language and call `apply_i18n` for them
+
+Tips:
+- Use distinct keys per plugin (prefix like `myplugin_`) to avoid collisions
+- Keep translations small and focused on end‑user strings
+- Prefer English as a base and verify JSON validity
+
 ## 5) Testing and logging
 
-- Use the GUI log (`gui.log.append(...)`) to provide feedback when applicable
+- Use the BCASL Studio (only_mod) to quickly iterate on your plugin:
+  - Launch: `python main.py --bcasl-only` or `python main.py bcasl`
+  - Select workspace, enable your plugin, reorder with drag‑and‑drop
+  - Pick a language from the Language combo or set the app’s global language
+  - Observe live i18n updates if your plugin implements `apply_i18n`
+- Prefer the provided Dialog/logging facilities to report information/warnings
 - Ensure code is idempotent and resilient to being called multiple times
 - Avoid blocking the UI thread; long operations should be asynchronous
 
@@ -101,6 +145,9 @@ Example `languages/en.json`:
 - [ ] Global `PLUGIN` instance
 - [ ] `on_pre_compile()` implemented and safe
 - [ ] Robust error handling (raise to abort build if necessary)
-- [ ] i18n files with `en.json` fallback
+- [ ] i18n files with `en.json` fallback under `languages/`
+- [ ] `apply_i18n(gui, tr)` implemented (supports preloaded dict or language code)
+- [ ] Plugin registered for i18n (`register_instance(plugin_id, instance)`)
+- [ ] Optional: expose `__package_dir__` or `get_package_dir()` for auto-discovery
 - [ ] Clear logs for users