From 9544f8a6829c6595f62bc902c396ed4afdec0fc1 Mon Sep 17 00:00:00 2001
From: Lachlan Reynolds <lachlan.reynolds@innocraft.com>
Date: Tue, 21 Apr 2026 14:34:53 +1200
Subject: [PATCH 1/2] docs: updated API documentation to be more consistent

---
 API.php | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/API.php b/API.php
index df5767e..7820dd4 100644
--- a/API.php
+++ b/API.php
@@ -16,9 +16,8 @@
 use Piwik\Plugins\CustomTranslations\TranslationTypes\TranslationTypeProvider;
 
 /**
- * Public API for managing CustomTranslations translation values and metadata.
- *
- * All endpoints exposed by this API require Super User access.
+ * Exposes Super User endpoints for listing translatable entities and storing custom label overrides.
+ * Saved translations are applied to supported dashboard, event, custom dimension, and custom report outputs.
  *
  * @method static \Piwik\Plugins\CustomTranslations\API getInstance()
  */
@@ -40,12 +39,13 @@ public function __construct(TranslationsDao $storage, TranslationTypeProvider $p
     }
 
     /**
-     * Sets (overwrites) the translations for a specific type. Make sure to pass all translations for the given type
-     * / language.
-     * @param string $idType
-     * @param string $languageCode
-     * @param array $translations  An array where (original value => translation)
-     * @throws \Exception If type, language, or translations is not valid
+     * Stores the full translation map for a specific type and language.
+     * Pass an empty array to remove any saved translations for that type and language.
+     *
+     * @param string $idType Translation type identifier returned by getTranslatableTypes().
+     * @param string $languageCode Language code to store translations for.
+     * @param array<string, string> $translations Map of original labels to replacement labels.
+     * @return void
      */
     public function setTranslations($idType, $languageCode, $translations = array())
     {
@@ -58,10 +58,11 @@ public function setTranslations($idType, $languageCode, $translations = array())
     }
 
     /**
-     * Get all existing translations for a specific type and language.
-     * @param string $idType
-     * @param string $languageCode
-     * @throws \Exception If type, language, or translations is not valid
+     * Returns the saved translations for a specific type and language.
+     *
+     * @param string $idType Translation type identifier returned by getTranslatableTypes().
+     * @param string $languageCode Language code to load translations for.
+     * @return array<string, string> Translation map keyed by the original label for the requested type and language.
      */
     public function getTranslationsForType($idType, $languageCode)
     {
@@ -84,8 +85,10 @@ private function checkLanguageAvailable($languageCode)
     }
 
     /**
-     * Get a list of all translatable types.
-     * @return array[]
+     * Lists the translation types that can be configured through this plugin.
+     *
+     * @return array<int, array{id: string, name: string, description: string, translationKeys: array<int, string>}>
+     *         Available translation type metadata, sorted by name.
      */
     public function getTranslatableTypes()
     {

From de67fbbe15ee4f180623c328af71e6ebbdfc41b2 Mon Sep 17 00:00:00 2001
From: Lachlan Reynolds <lachlan.reynolds@innocraft.com>
Date: Wed, 22 Apr 2026 10:56:30 +1200
Subject: [PATCH 2/2] Updated changelog

---
 CHANGELOG.md | 5 +++++
 plugin.json  | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0db99bd..0bba5fd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,10 @@
 ## Changelog
 
+### 5.0.3 - 27/04/2026
+
+- Updated API documentation
+
+
 ### 5.0.2 - 02/03/2026
 
 - Updated API documentation
diff --git a/plugin.json b/plugin.json
index dc5c60c..70a26af 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "CustomTranslations",
   "description": "Translate entities and tracked values into different languages. For example Custom dimensions, dashboard names, custom report names, event values, ...",
-  "version": "5.0.2",
+  "version": "5.0.3",
   "theme": false,
   "require": {
     "matomo": ">=5.0.0-b1,<6.0.0-b1"