TheStreamCode · TheStreamCode · Sep 22, 2026 · Sep 22, 2026 · Sep 22, 2026 · Sep 22, 2026
diff --git a/README.de.md b/README.de.md
@@ -4,7 +4,7 @@
 [![WordPress Plugin Version](https://img.shields.io/wordpress/plugin/v/mikesoft-teamvault?label=WordPress.org)](https://wordpress.org/plugins/mikesoft-teamvault/)
 [![WordPress Tested](https://img.shields.io/wordpress/plugin/tested/mikesoft-teamvault?label=Tested%20up%20to)](https://wordpress.org/plugins/mikesoft-teamvault/)
 [![PHP](https://img.shields.io/badge/PHP-8.0%2B-777BB4?logo=php&logoColor=white)](https://www.php.net/)
-[![License](https://img.shields.io/badge/License-GPL%20v2%2B-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/License-GPL--2.0--or--later-blue.svg)](LICENSE)
 [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-db61a2?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/TheStreamCode)
 
 [English](README.md) · [Italiano](README.it.md) · [Français](README.fr.md) · [Español](README.es.md) · **Deutsch**

diff --git a/README.es.md b/README.es.md
@@ -4,7 +4,7 @@
 [![WordPress Plugin Version](https://img.shields.io/wordpress/plugin/v/mikesoft-teamvault?label=WordPress.org)](https://wordpress.org/plugins/mikesoft-teamvault/)
 [![WordPress Tested](https://img.shields.io/wordpress/plugin/tested/mikesoft-teamvault?label=Tested%20up%20to)](https://wordpress.org/plugins/mikesoft-teamvault/)
 [![PHP](https://img.shields.io/badge/PHP-8.0%2B-777BB4?logo=php&logoColor=white)](https://www.php.net/)
-[![License](https://img.shields.io/badge/License-GPL%20v2%2B-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/License-GPL--2.0--or--later-blue.svg)](LICENSE)
 [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-db61a2?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/TheStreamCode)
 
 [English](README.md) · [Italiano](README.it.md) · [Français](README.fr.md) · **Español** · [Deutsch](README.de.md)

diff --git a/README.fr.md b/README.fr.md
@@ -4,7 +4,7 @@
 [![WordPress Plugin Version](https://img.shields.io/wordpress/plugin/v/mikesoft-teamvault?label=WordPress.org)](https://wordpress.org/plugins/mikesoft-teamvault/)
 [![WordPress Tested](https://img.shields.io/wordpress/plugin/tested/mikesoft-teamvault?label=Tested%20up%20to)](https://wordpress.org/plugins/mikesoft-teamvault/)
 [![PHP](https://img.shields.io/badge/PHP-8.0%2B-777BB4?logo=php&logoColor=white)](https://www.php.net/)
-[![License](https://img.shields.io/badge/License-GPL%20v2%2B-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/License-GPL--2.0--or--later-blue.svg)](LICENSE)
 [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-db61a2?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/TheStreamCode)
 
 [English](README.md) · [Italiano](README.it.md) · **Français** · [Español](README.es.md) · [Deutsch](README.de.md)

diff --git a/README.it.md b/README.it.md
@@ -4,7 +4,7 @@
 [![WordPress Plugin Version](https://img.shields.io/wordpress/plugin/v/mikesoft-teamvault?label=WordPress.org)](https://wordpress.org/plugins/mikesoft-teamvault/)
 [![WordPress Tested](https://img.shields.io/wordpress/plugin/tested/mikesoft-teamvault?label=Tested%20up%20to)](https://wordpress.org/plugins/mikesoft-teamvault/)
 [![PHP](https://img.shields.io/badge/PHP-8.0%2B-777BB4?logo=php&logoColor=white)](https://www.php.net/)
-[![License](https://img.shields.io/badge/License-GPL%20v2%2B-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/License-GPL--2.0--or--later-blue.svg)](LICENSE)
 [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-db61a2?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/TheStreamCode)
 
 [English](README.md) · **Italiano** · [Français](README.fr.md) · [Español](README.es.md) · [Deutsch](README.de.md)

diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@
   <a href="https://wordpress.org/plugins/mikesoft-teamvault/"><img src="https://img.shields.io/wordpress/plugin/v/mikesoft-teamvault?label=WordPress.org" alt="WordPress Plugin Version"></a>
   <a href="https://wordpress.org/plugins/mikesoft-teamvault/"><img src="https://img.shields.io/wordpress/plugin/tested/mikesoft-teamvault?label=Tested%20up%20to" alt="WordPress Tested"></a>
   <a href="https://www.php.net/"><img src="https://img.shields.io/badge/PHP-8.0%2B-777BB4?logo=php&amp;logoColor=white" alt="PHP 8.0+"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-GPL%20v2%2B-blue.svg" alt="GPL v2 or later"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-GPL--2.0--or--later-blue.svg" alt="GPL-2.0-or-later"></a>
 </p>
 
 <p align="center"><strong>English</strong> · <a href="README.it.md">Italiano</a> · <a href="README.fr.md">Français</a> · <a href="README.es.md">Español</a> · <a href="README.de.md">Deutsch</a></p>
@@ -227,10 +227,11 @@ These assets serve different surfaces and should stay aligned to the same brand
 ## Documentation Map
 
 - [`docs/developer/hooks.md`](docs/developer/hooks.md) - developer hooks and filters
+- [`docs/developer/i18n.md`](docs/developer/i18n.md) - translation workflow (textdomain, POT, GlotPress handoff)
 - [`docs/maintainer/local-development.md`](docs/maintainer/local-development.md) - local development workflow
 - [`docs/maintainer/release.md`](docs/maintainer/release.md) - WordPress.org release process
 - [`docs/maintainer/security-review.md`](docs/maintainer/security-review.md) - latest repository security review and residual risks
 
 ## License
 
-This project is licensed under the [GNU General Public License v2.0](LICENSE), or (at your option) any later version.
+This project is licensed under `GPL-2.0-or-later` — the [GNU General Public License v2.0](LICENSE), or (at your option) any later version.
diff --git a/docs/developer/i18n.md b/docs/developer/i18n.md
@@ -0,0 +1,47 @@
+# Internationalization (i18n)
+
+TeamVault follows the standard WordPress.org translation workflow so
+translators can collaborate in GlotPress instead of editing PHP.
+
+## How it works
+
+- All user-facing strings use the `mikesoft-teamvault` text domain
+  (`__()`, `esc_html__()`, `esc_attr__()`, `esc_html_e()` …).
+- `MSTV_I18n::init()` (runs on `init` via `MSTV_Bootstrap::init_services()`)
+  loads community language packs with the standard call:
+
+  ```php
+  load_plugin_textdomain('mikesoft-teamvault', false, dirname(plugin_basename(__FILE__), 2) . '/languages');
+  ```
+
+  (`__FILE__` is `includes/class-mstv-i18n.php`, hence dirname level 2.)
+- `languages/mikesoft-teamvault.pot` is the translatable-string template
+  shipped for GlotPress import.
+- The hardcoded it/fr/es/de maps in `includes/class-mstv-i18n.php` stay as a
+  **runtime fallback** (via the `gettext` filter) so the bundled interface
+  languages keep working when no language pack is installed. They are not the
+  translation source of truth — GlotPress is.
+
+## Regenerating the POT
+
+Preferred (requires wp-cli):
+
+```sh
+wp i18n make-pot . languages/mikesoft-teamvault.pot --domain=mikesoft-teamvault
+```
+
+The committed POT was produced with an equivalent extractor (same function
+set and `mikesoft-teamvault` domain filter, `#: file:line` references,
+`Plural-Forms: nplurals=2; plural=(n != 1);`) because wp-cli was unavailable;
+re-running `wp i18n make-pot` is welcome to normalize it.
+
+## GlotPress handoff
+
+1. Import the updated `.pot` into the
+   [WordPress.org plugin GlotPress project](https://translate.wordpress.org/projects/wp-plugins/mikesoft-teamvault/)
+   on release.
+2. Approved translations ship automatically as WordPress.org language packs
+   into `wp-content/languages/plugins/` — no bundled `.po`/`.mo` files needed.
+3. Keep the fallback maps in sync only until GlotPress coverage for a locale
+   is complete; the maps must always cover every `mikesoft-teamvault` string
+   (guarded by `tests/PdmI18nCoverageTest.php`).
diff --git a/includes/class-mstv-i18n.php b/includes/class-mstv-i18n.php
@@ -1263,6 +1263,13 @@ class MSTV_I18n
 
     public function init(): void
     {
+        // No load_plugin_textdomain() call: this plugin is hosted on
+        // wordpress.org with "Requires at least: 6.0" (well above 4.6), so
+        // WordPress auto-loads GlotPress language packs from WP_LANG_DIR.
+        // See https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#plugins-on-wordpress-org
+
+        // Runtime fallback: in-admin maps below keep the bundled it/fr/es/de
+        // interface working when no language pack is installed (see docs/developer/i18n.md).
         add_filter('gettext', [$this, 'filter_gettext'], 20, 3);
     }