i18n: Add documentation article (#5866)

* i18n: Add documentation article

* Fix sidebar

* Fix typo

* More consistent term usage

Author: oitel

doxygen/general_pages/I18nGuide.dox

@@ -0,0 +1,354 @@
+/**
+
+\page I18nGuide Internationalization Guide
+
+\tableofcontents
+
+MeshLib uses a <a href="https://www.gnu.org/software/gettext/">gettext</a>-compatible localization system backed by
+<a href="https://www.boost.org/doc/libs/release/libs/locale/">Boost.Locale</a>.
+Translatable strings are marked in C++ source code, extracted to template files, translated per language,
+compiled to binary catalogs, and loaded at runtime.
+
+This guide explains how to integrate and use the i18n system in your own MeshLib-based project.
+
+# File formats and directory layout {#I18nFileFormats}
+
+The gettext toolchain uses three file types:
+
+- `.pot` - Master list of all extractable strings for a domain. Generated by `xgettext`.
+- `.po` - Per-language translation file. Each `msgid` has a corresponding `msgstr` filled in by a translator.
+- `.mo` - Compiled from `.po` files by `msgfmt`. Loaded at runtime by Boost.Locale.
+
+Source translations live under a `locale/` directory at the project root:
+
+\code
+locale/
+  MyPlugin.pot                           <- template (all extractable strings)
+  MRRibbonMyMenu.pot                     <- template for ribbon JSON strings
+  de/
+    MyPlugin.po                          <- German translations
+    MRRibbonMyMenu.po
+  fr/
+    MyPlugin.po                          <- French translations
+    MRRibbonMyMenu.po
+\endcode
+
+At build time, `.po` files are compiled to `.mo` and placed in the output directory:
+
+\code
+<build>/locale/<lang>/LC_MESSAGES/<Domain>.mo
+\endcode
+
+For example: `build/Release/bin/locale/de/LC_MESSAGES/MyPlugin.mo`.
+
+\note The domain name is always derived from the filename stem: `MyPlugin.po` belongs to domain `"MyPlugin"`.
+
+# Gettext utilities and helper scripts {#I18nTooling}
+
+## Prerequisites
+
+- **gettext tools**: `xgettext`, `msgmerge`, `msgfmt`. Install via your OS package manager. On Windows, set the `GETTEXT_ROOT` environment variable to the install prefix.
+- **Python 3** for the helper scripts in `scripts/gettext/`.
+
+## Helper scripts
+
+All scripts are in `scripts/gettext/`:
+
+- `update_translations.py` - Runs `xgettext` over C++ sources to produce or update a `.pot` template, then runs `msgmerge` to bring existing `.po` files in sync.
+- `update_json_translations.py` - Extracts translatable fields from `.items.json` and `.ui.json` ribbon menu files into a `.pot`, then merges existing `.po` files.
+- `compile_translations.py` - Compiles every `.po` file under `locale/` to `.mo` using `msgfmt`.
+
+### Extracting C++ strings
+
+\code{.sh}
+python3 scripts/gettext/update_translations.py \
+    locale/MyPlugin.pot \
+    source/MyPlugin/
+\endcode
+
+This scans all `.cpp`, `.h`, and `.hpp` files and extracts strings marked by the recognized macros.
+
+### Extracting JSON strings
+
+\code{.sh}
+python3 scripts/gettext/update_json_translations.py \
+    locale/MRRibbonMyMenu.pot \
+    source/MyPlugin/MRRibbonMyMenu.items.json
+\endcode
+
+### Compiling translations
+
+\code{.sh}
+python3 scripts/gettext/compile_translations.py \
+    locale/ \
+    build/Release/bin/locale/
+\endcode
+
+This produces `build/Release/bin/locale/<lang>/LC_MESSAGES/<Domain>.mo` for every `.po` found.
+
+## CMake integration
+
+`cmake/Modules/I18nHelpers.cmake` provides the `mr_add_translations()` function:
+
+\code{.cmake}
+include(I18nHelpers)
+
+mr_add_translations(myplugin_translations
+  DOMAINS
+    MyPlugin
+    MRRibbonMyMenu
+  PATHS
+    "${CMAKE_CURRENT_PROJECT_DIR}/locale"
+)
+if(TARGET myplugin_translations)
+  add_dependencies(MyApp myplugin_translations)
+endif()
+\endcode
+
+The function:
+1. Finds `msgfmt` (respects `GETTEXT_ROOT` / `$ENV{GETTEXT_ROOT}`).
+2. For each domain and path, locates every `<path>/<lang>/<domain>.po` file.
+3. Creates custom commands that compile each `.po` to `.mo` at build time.
+4. Creates a custom target depending on all `.mo` files.
+5. Installs `.pot` templates and compiled `.mo` files to `${MR_RESOURCES_DIR}/locale/`.
+
+If `msgfmt` is not found, the function silently does nothing and no target is created. This is why the `if(TARGET ...)` guard is needed before `add_dependencies`.
+
+# In-app initialization and configuration {#I18nInit}
+
+## Automatic initialization
+
+Some configuration is performed automatically during the MRViewer library loading:
+1. Registration of the default domain `"MeshLib"`.
+2. Adding the default catalog path: `SystemPath::getResourcesDirectory() / "locale"`.
+
+The initial locale is `"en"` (i.e. no translations applied).
+
+## Registering a custom domain
+
+Call `addDomain()` once and use a returned value from `findDomain()`, before any translations from that domain are needed:
+
+\code{.cpp}
+#include <MRViewer/MRLocale.h>
+
+MR::Locale::addDomain( "MyPlugin" );
+
+static const int kMyDomainId = MR::Locale::findDomain( "MyPlugin" );
+\endcode
+
+The returned integer is stable for the process lifetime. You can pass it to `translate()` via `MR::Locale::Domain{ kMyDomainId }`.
+
+## Registering a custom catalog path
+
+If your plugin stores `.mo` files outside the standard resources directory, register the path before any UI is shown:
+
+\code{.cpp}
+MR::Locale::addCatalogPath( myPlugin.resourceDir() / "locale" );
+\endcode
+
+Paths are deduplicated. Every call to `addCatalogPath` or `addDomain` regenerates the active locale object, so new catalogs are available immediately.
+
+## Switching locale at runtime
+
+\code{.cpp}
+MR::Locale::set( "ko" );   // switch to Korean
+MR::Locale::set( "en" );   // back to English
+\endcode
+
+`set()` fires the `onChanged` signal synchronously before returning.
+
+## Reacting to locale changes
+
+\code{.cpp}
+boost::signals2::connection conn = MR::Locale::onChanged( [&]( const std::string& localeName )
+{
+    // rebuild cached translated strings, tooltips, etc.
+    rebuildUI();
+} );
+\endcode
+
+## Defining human-readable locale names
+
+Many common languages and regions already have a pre-loaded human-readable name provided by CLDR.
+If your locale is not in the list, you can add it in runtime.
+
+\code{.cpp}
+MR::Locale::setDisplayName( "my_variant", "My Language (Special)" );
+\endcode
+
+# Translation functions and macros {#I18nAPI}
+
+## Macros
+
+All macros are defined in `MRViewer/MRI18n.h`, except `_t`, which is in `MRMesh/MRMeshFwd.h`:
+
+- `_tr("text")` - UI labels passed directly to ImGui/UI functions.
+- `s_tr("text")` - When you need an owning string (storage, concatenation). 
+- `f_tr("text {}")` - Format strings for `fmt::format()`.
+- `_t("text")` - Marking strings for extraction in contexts where the original value must be returned (see an example below).
+
+\warning `_tr()` returns a pointer into a **temporary** `std::string` that is destroyed at the end of the full expression. Always consume `_tr()` in the same expression, or use `s_tr()` / `MR::Locale::translate()` to store the result.
+
+\code{.cpp}
+// CORRECT: consumed in the same expression
+UI::button( _tr( "Save" ), size );
+ImGui::Text( "%s", _tr( "Label" ) );
+
+// WRONG: dangling pointer
+const auto label = _tr( "Save" );
+UI::button( label, size );              // undefined behavior
+
+// CORRECT: store as std::string
+const auto label = s_tr( "Save" );
+UI::button( label.c_str(), size );
+\endcode
+
+## Direct translate functions
+
+`MR::Locale::translate()` accepts an optional `Domain` parameter:
+
+\code{.cpp}
+// simple message (default MeshLib domain)
+std::string t = MR::Locale::translate( "Open" );
+
+// with explicit domain
+std::string t = MR::Locale::translate( "Open", MR::Locale::Domain{ kMyDomainId } );
+
+// context disambiguation
+std::string t = MR::Locale::translate( "Camera", "View" );
+
+// plural form
+std::string t = MR::Locale::translate( "%d item", "%d items", count );
+
+// batch translation for combo lists
+auto items = MR::Locale::translateAll( kModeNames );
+auto items = MR::Locale::translateAll( "context", kModeNames );
+\endcode
+
+## Static arrays and deferred translation
+
+Mark strings with `_t()` at declaration time so `xgettext` extracts them, then translate at display time:
+
+\code{.cpp}
+// declaration: _t() is a no-op, strings are stored untranslated
+static const std::vector<std::string> kModeNames {
+    _t( "Append" ),
+    _t( "Replace" ),
+};
+
+// display: translate on every frame
+UI::combo( _tr( "Mode" ), &idx, MR::Locale::translateAll( kModeNames ) );
+\endcode
+
+## Context disambiguation
+
+When the same English string has different meanings, use the context overload:
+
+\code{.cpp}
+// "View" as a noun (saved camera view) vs. verb (to view something)
+ImGui::Text( "%s", _tr( "Camera", "View" ) );
+ImGui::Text( "%s", _tr( "Action", "View" ) );
+\endcode
+
+In the `.po` file these appear as separate entries with different `msgctxt` values.
+
+## Plural forms
+
+\code{.cpp}
+auto label = MR::Locale::translate( "%d item", "%d items", count );
+\endcode
+
+The correct form is selected by Boost.Locale based on the `Plural-Forms:` rule in the `.po` header.
+
+## TRANSLATORS comments
+
+Place a `// TRANSLATORS:` comment on the line immediately before a translatable string to give translators context.
+`xgettext` picks these up and includes them as `#.` comment lines in the `.pot` file:
+
+\code{.cpp}
+// TRANSLATORS: Shown when the mesh has no faces after repair
+ImGui::Text( "%s", _tr( "Empty result" ) );
+\endcode
+
+## Custom header file for your domain {#I18nCustomHeader}
+
+When building a plugin with its own translation domain, create a project-local header file
+that redefines the macros to use your domain automatically. This way, every `_tr()` call in your plugin
+looks up the correct catalog without passing domain IDs explicitly.
+
+Copy and adapt the following template (also available at `examples/cpp-samples/MRI18nDomainExample.h`):
+
+\snippet MRI18nDomainExample.h custom-domain-header
+
+To use this header in your plugin:
+
+1. Include your local header file instead of `<MRViewer/MRI18n.h>` in every `.cpp` file.
+2. Register the domain at startup: `MR::Locale::addDomain( MY_PLUGIN_I18N_DOMAIN );`
+3. All `_tr()`, `s_tr()`, and `f_tr()` calls will now use your domain.
+
+\note `findDomain()` performs a cache lookup by pointer address for `const char*` literals, so the runtime cost is minimal.
+
+# Translating JSON menu files {#I18nJSON}
+
+MeshLib's ribbon menu system loads tool definitions from `.items.json` and UI layout from `.ui.json` files.
+Both formats contain translatable strings.
+
+## .items.json
+
+Each entry in the `"Items"` array may contain:
+- **"Caption"** - the display label (falls back to **"Name"** if absent).
+- **"Tooltip"** - the tooltip text.
+
+\code{.json}
+{
+  "Items": [
+    {
+      "Name": "My Tool",
+      "Caption": "My Custom Tool",
+      "Tooltip": "Performs a custom operation on the mesh"
+    }
+  ]
+}
+\endcode
+
+See \ref ExamplePluginOverview for a complete plugin JSON example.
+
+## .ui.json
+
+Tab names in the `"Tabs"` array are extracted with the context `"Tab name"`:
+
+\code{.json}
+{
+  "Order": 10,
+  "LibName": "MyPlugin",
+  "Tabs": [
+    {
+      "Name": "Analysis",
+      "Groups": [ ... ]
+    }
+  ]
+}
+\endcode
+
+## Domain auto-registration
+
+When the ribbon schema loader reads a `.items.json` file, it automatically registers a domain from the filename stem.
+For example, loading `MRRibbonMyMenu.items.json` calls `Locale::addDomain( "MRRibbonMyMenu" )` and stores the
+returned domain ID in each `MenuItemInfo`. The matching `.ui.json` then uses `Locale::findDomain()` with the same stem.
+
+This means ribbon menu strings are translated from their own domain catalog, separate from your C++ code strings.
+
+## Extracting JSON strings
+
+Run `update_json_translations.py` for each JSON pair:
+
+\code{.sh}
+python3 scripts/gettext/update_json_translations.py \
+    locale/MRRibbonMyMenu.pot \
+    source/MyPlugin/MRRibbonMyMenu.items.json
+\endcode
+
+The script extracts `"Caption"` (or `"Name"`) and `"Tooltip"` from `.items.json`, and tab `"Name"` fields
+(with context `"Tab name"`) from the matching `.ui.json`.
+
+*/

doxygen/general_pages/PackageOverview.dox

@@ -11,5 +11,6 @@
  - \ref ExamplePluginOverview
  - \ref StatePluginsHelp
  - \ref HowtoAddPluginOverview
+ - \ref I18nGuide
 
-*/
+*/

doxygen/layout_templates/base_struct.xml

@@ -72,6 +72,7 @@
       <tab type="user" url="__BEGIN_URL__ExamplePluginOverview__END_URL__" title="How to use С++ Example Plugin"/>
       <tab type="user" url="__BEGIN_URL__StatePluginsHelp__END_URL__" title="State Plugins Overview"/>
       <tab type="user" url="__BEGIN_URL__HowtoAddPluginOverview__END_URL__" title="How to Add Plugin"/>
+      <tab type="user" url="__BEGIN_URL__I18nGuide__END_URL__" title="Internationalization Guide"/>
     </tab>
     <tab type="usergroup" url="__BEGIN_URL__APIPage__END_URL__" title="API">
       <!-- API_CPP_PAGE -->

examples/cpp-samples/MRI18nDomainExample.h

@@ -0,0 +1,20 @@
+//! [custom-domain-header]
+#pragma once
+
+#include <MRViewer/MRI18n.h>
+
+// forward declaration from MRLocale.h
+namespace MR::Locale { MRVIEWER_API int findDomain( const char* domainName ); }
+
+// replace "MyPlugin" with your actual domain name
+// (must match the .pot/.po filename stem)
+inline constexpr const char* MY_PLUGIN_I18N_DOMAIN = "MyPlugin";
+
+// redefine the i18n macros to use your domain by default
+#undef _tr
+#undef s_tr
+#undef f_tr
+#define _tr( ... ) MR::Locale::translate( __VA_ARGS__, MR::Locale::Domain{ MR::Locale::findDomain( MY_PLUGIN_I18N_DOMAIN ) } ).c_str()
+#define s_tr( ... ) MR::Locale::translate( __VA_ARGS__, MR::Locale::Domain{ MR::Locale::findDomain( MY_PLUGIN_I18N_DOMAIN ) } )
+#define f_tr( ... ) fmt::runtime( MR::Locale::translate( __VA_ARGS__, MR::Locale::Domain{ MR::Locale::findDomain( MY_PLUGIN_I18N_DOMAIN ) } ) )
+//! [custom-domain-header]