From 5ce59f37f18bb4baae633f0fd2b8f1d80bdb5619 Mon Sep 17 00:00:00 2001
From: Ahmet Bora <byybora@gmail.com>
Date: Fri, 26 Jan 2024 16:59:24 +0300
Subject: [PATCH 1/6] New `translations` root

---
 config/areas/languages/views.php |   4 +-
 src/Cms/AppTranslations.php      |  12 ++-
 src/Cms/Core.php                 |  53 ++++++------
 src/Cms/Language.php             |  30 +++++--
 src/Cms/LanguageTranslations.php | 141 +++++++++++++++++++++++++++++++
 src/Cms/LanguageVariable.php     |  18 ++--
 6 files changed, 211 insertions(+), 47 deletions(-)
 create mode 100644 src/Cms/LanguageTranslations.php

diff --git a/config/areas/languages/views.php b/config/areas/languages/views.php
index 2dcdcd84a3..19d49ec816 100644
--- a/config/areas/languages/views.php
+++ b/config/areas/languages/views.php
@@ -17,8 +17,8 @@
 			$language     = Find::language($code);
 			$link         = '/languages/' . $language->code();
 			$strings      = [];
-			$foundation   = $kirby->defaultLanguage()->translations();
-			$translations = $language->translations();
+			$foundation   = $kirby->defaultLanguage()->translations()->toArray();
+			$translations = $language->translations()->toArray();
 
 			// TODO: update following line and adapt for update and
 			// delete options when `languageVariables.*` permissions available
diff --git a/src/Cms/AppTranslations.php b/src/Cms/AppTranslations.php
index 896c0e7498..1dc6880b04 100644
--- a/src/Cms/AppTranslations.php
+++ b/src/Cms/AppTranslations.php
@@ -31,7 +31,10 @@ protected function i18n(): void
 				$this->multilang() === true &&
 				$language = $this->languages()->find($locale)
 			) {
-				$data = [...$data, ...$language->translations()];
+				$data = [
+					...$data,
+					...$language->translations()->toArray()
+				];
 			}
 
 
@@ -135,7 +138,10 @@ public function translation(string|null $locale = null): Translation
 
 		// inject current language translations
 		if ($language = $this->language($locale)) {
-			$inject = [...$inject, ...$language->translations()];
+			$inject = [
+				...$inject,
+				...$language->translations()->toArray()
+			];
 		}
 
 		// load from disk instead
@@ -161,7 +167,7 @@ public function translations(): Translations
 		if ($languages = $this->languages()) {
 			foreach ($languages as $language) {
 				$languageCode         = $language->code();
-				$languageTranslations = $language->translations();
+				$languageTranslations = $language->translations()->toArray();
 
 				// merges language translations with extensions translations
 				if (empty($languageTranslations) === false) {
diff --git a/src/Cms/Core.php b/src/Cms/Core.php
index b14dc6d2ce..ee5c8216dc 100644
--- a/src/Cms/Core.php
+++ b/src/Cms/Core.php
@@ -331,33 +331,34 @@ public function load(): Loader
 	public function roots(): array
 	{
 		return $this->cache['roots'] ??= [
-			'kirby'       => fn (array $roots) => dirname(__DIR__, 2),
-			'i18n'        => fn (array $roots) => $roots['kirby'] . '/i18n',
+			'kirby'        => fn (array $roots) => dirname(__DIR__, 2),
+			'i18n'         => fn (array $roots) => $roots['kirby'] . '/i18n',
 			'i18n:translations' => fn (array $roots) => $roots['i18n'] . '/translations',
-			'i18n:rules'  => fn (array $roots) => $roots['i18n'] . '/rules',
-
-			'index'       => fn (array $roots) => static::$indexRoot ?? dirname(__DIR__, 3),
-			'assets'      => fn (array $roots) => $roots['index'] . '/assets',
-			'content'     => fn (array $roots) => $roots['index'] . '/content',
-			'media'       => fn (array $roots) => $roots['index'] . '/media',
-			'panel'       => fn (array $roots) => $roots['kirby'] . '/panel',
-			'site'        => fn (array $roots) => $roots['index'] . '/site',
-			'accounts'    => fn (array $roots) => $roots['site'] . '/accounts',
-			'blueprints'  => fn (array $roots) => $roots['site'] . '/blueprints',
-			'cache'       => fn (array $roots) => $roots['site'] . '/cache',
-			'collections' => fn (array $roots) => $roots['site'] . '/collections',
-			'commands'    => fn (array $roots) => $roots['site'] . '/commands',
-			'config'      => fn (array $roots) => $roots['site'] . '/config',
-			'controllers' => fn (array $roots) => $roots['site'] . '/controllers',
-			'languages'   => fn (array $roots) => $roots['site'] . '/languages',
-			'license'     => fn (array $roots) => $roots['config'] . '/.license',
-			'logs'        => fn (array $roots) => $roots['site'] . '/logs',
-			'models'      => fn (array $roots) => $roots['site'] . '/models',
-			'plugins'     => fn (array $roots) => $roots['site'] . '/plugins',
-			'sessions'    => fn (array $roots) => $roots['site'] . '/sessions',
-			'snippets'    => fn (array $roots) => $roots['site'] . '/snippets',
-			'templates'   => fn (array $roots) => $roots['site'] . '/templates',
-			'roles'       => fn (array $roots) => $roots['blueprints'] . '/users',
+			'i18n:rules'   => fn (array $roots) => $roots['i18n'] . '/rules',
+
+			'index'        => fn (array $roots) => static::$indexRoot ?? dirname(__DIR__, 3),
+			'assets'       => fn (array $roots) => $roots['index'] . '/assets',
+			'content'      => fn (array $roots) => $roots['index'] . '/content',
+			'media'        => fn (array $roots) => $roots['index'] . '/media',
+			'panel'        => fn (array $roots) => $roots['kirby'] . '/panel',
+			'site'         => fn (array $roots) => $roots['index'] . '/site',
+			'accounts'     => fn (array $roots) => $roots['site'] . '/accounts',
+			'blueprints'   => fn (array $roots) => $roots['site'] . '/blueprints',
+			'cache'        => fn (array $roots) => $roots['site'] . '/cache',
+			'collections'  => fn (array $roots) => $roots['site'] . '/collections',
+			'commands'     => fn (array $roots) => $roots['site'] . '/commands',
+			'config'       => fn (array $roots) => $roots['site'] . '/config',
+			'controllers'  => fn (array $roots) => $roots['site'] . '/controllers',
+			'languages'    => fn (array $roots) => $roots['site'] . '/languages',
+			'license'      => fn (array $roots) => $roots['config'] . '/.license',
+			'logs'         => fn (array $roots) => $roots['site'] . '/logs',
+			'models'       => fn (array $roots) => $roots['site'] . '/models',
+			'plugins'      => fn (array $roots) => $roots['site'] . '/plugins',
+			'roles'        => fn (array $roots) => $roots['blueprints'] . '/users',
+			'sessions'     => fn (array $roots) => $roots['site'] . '/sessions',
+			'snippets'     => fn (array $roots) => $roots['site'] . '/snippets',
+			'templates'    => fn (array $roots) => $roots['site'] . '/templates',
+			'translations' => null,
 		];
 	}
 
diff --git a/src/Cms/Language.php b/src/Cms/Language.php
index a8be660bdc..26941e1137 100644
--- a/src/Cms/Language.php
+++ b/src/Cms/Language.php
@@ -48,7 +48,7 @@ class Language implements Stringable
 	protected bool $single;
 	protected array $slugs;
 	protected array $smartypants;
-	protected array $translations;
+	protected LanguageTranslations $translations;
 	protected string|null $url;
 
 	/**
@@ -68,7 +68,6 @@ public function __construct(array $props)
 		$this->single       = $props['single'] ?? false;
 		$this->slugs        = $props['slugs'] ?? [];
 		$this->smartypants  = $props['smartypants'] ?? [];
-		$this->translations = $props['translations'] ?? [];
 		$this->url          = $props['url'] ?? null;
 
 		if ($locale = $props['locale'] ?? null) {
@@ -76,6 +75,8 @@ public function __construct(array $props)
 		} else {
 			$this->locale = [LC_ALL => $this->code];
 		}
+
+		$this->translations = new LanguageTranslations($this, $props['translations'] ?? []);
 	}
 
 	/**
@@ -130,7 +131,7 @@ public function clone(array $props = []): static
 			'name'         => $this->name,
 			'slugs'        => $this->slugs,
 			'smartypants'  => $this->smartypants,
-			'translations' => $this->translations,
+			'translations' => $this->translations->toArray(),
 			'url'          => $this->url,
 		], $props));
 	}
@@ -471,6 +472,7 @@ public function save(): static
 	{
 		try {
 			$existingData = Data::read($this->root());
+			$data['translations'] = $this->translations()->load($existingData['translations'] ?? []);
 		} catch (Throwable) {
 			$existingData = [];
 		}
@@ -482,12 +484,19 @@ public function save(): static
 			'direction'    => $this->direction(),
 			'locale'       => Locale::export($this->locale()),
 			'name'         => $this->name(),
-			'translations' => $this->translations(),
+			'translations' => $this->translations()->toArray(),
 			'url'          => $this->url,
 		];
 
 		ksort($data);
 
+		// save translations to the custom root and remove translations
+		// to prevent duplication write into the language file
+		if ($this->translations()->root() !== null) {
+			$this->translations()->save($data['translations'] ?? []);
+			$data['translations'] = [];
+		}
+
 		Data::write($this->root(), $data);
 
 		return $this;
@@ -548,9 +557,9 @@ public function toArray(): array
 	}
 
 	/**
-	 * Returns the translation strings for this language
+	 * Returns the language translations object for this language
 	 */
-	public function translations(): array
+	public function translations(): LanguageTranslations
 	{
 		return $this->translations;
 	}
@@ -579,6 +588,15 @@ public function update(array|null $props = null): static
 		// make sure the slug is nice and clean
 		$props['slug'] = Str::slug($props['slug'] ?? null);
 
+		$kirby   = App::instance();
+		$updated = $this->clone($props);
+
+		if (isset($props['translations']) === true) {
+			$updated->translations = new LanguageTranslations($updated, $props['translations']);
+		}
+
+		// validate the updated language
+		LanguageRules::update($updated);
 
 		// trigger before hook
 		$language = $kirby->apply(
diff --git a/src/Cms/LanguageTranslations.php b/src/Cms/LanguageTranslations.php
new file mode 100644
index 0000000000..622f60bc2c
--- /dev/null
+++ b/src/Cms/LanguageTranslations.php
@@ -0,0 +1,141 @@
+<?php
+
+namespace Kirby\Cms;
+
+use Exception;
+use Kirby\Data\Data;
+use Kirby\Filesystem\F;
+
+/**
+ * With helper methods provides get language translations or
+ * loads from custom `translations` root
+ * @since 5.0.0
+ *
+ * @package   Kirby Cms
+ * @author    Ahmet Bora <ahmet@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://getkirby.com/license
+ */
+class LanguageTranslations
+{
+	protected App   $kirby;
+	protected array $data;
+
+	public function __construct(
+		protected Language $language,
+		self|array $translations = []
+	) {
+		$this->kirby = App::instance();
+		$this->setTranslations($translations);
+	}
+
+	/**
+	 * Returns a single translation string by key
+	 */
+	public function get(string $key, string $default = null): string|null
+	{
+		return $this->data[$key] ?? $default;
+	}
+
+	/**
+	 * Loads the language translations based on custom roots for provided language code
+	 */
+	public function load(array $default = []): array
+	{
+		if ($file = static::root()) {
+			try {
+				return Data::read($file);
+			} catch (Exception) {
+				return $default;
+			}
+		}
+
+		return $default;
+	}
+
+	/**
+	 * Saves the language translations in the custom root
+	 * @internal
+	 *
+	 * @return $this
+	 */
+	public function save(array $translations = []): static
+	{
+		if ($root = $this->root()) {
+			$this->data = $translations;
+			Data::write($root, $translations);
+		}
+
+		return $this;
+	}
+
+	/**
+	 * Returns custom translations root path if defined
+	 */
+	public function root(): string|null
+	{
+		$kirby = App::instance();
+		$root  = $kirby->root('translations');
+		$file  = $root . '/' . $this->language->code() . '.php';
+
+		if (
+			$root !== null &&
+			F::exists($file) === true
+		) {
+			return $file;
+		}
+
+		return null;
+	}
+
+	/**
+	 * Removes a translation key
+	 *
+	 * @return $this
+	 */
+	public function remove(string $key): static
+	{
+		unset($this->data[$key]);
+		return $this;
+	}
+
+	/**
+	 * Sets the translation key
+	 *
+	 * @return $this
+	 */
+	public function set(string $key, string|null $value = null): static
+	{
+		$this->data[$key] = $value;
+		return $this;
+	}
+
+	/**
+	 * Set translations
+	 *
+	 * @return $this
+	 */
+	public function setTranslations(self|array $translations = []): static
+	{
+		if (empty($translations) === false) {
+			if ($translations instanceof self) {
+				$this->data = $translations->toArray();
+			} else {
+				$this->data = $translations;
+			}
+		} else {
+			$this->data = static::load();
+		}
+
+		return $this;
+	}
+
+	/**
+	 * Returns translations
+	 */
+	public function toArray(): array
+	{
+		return $this->data;
+	}
+}
diff --git a/src/Cms/LanguageVariable.php b/src/Cms/LanguageVariable.php
index 7ca846bf87..6632353eb8 100644
--- a/src/Cms/LanguageVariable.php
+++ b/src/Cms/LanguageVariable.php
@@ -46,7 +46,7 @@ public static function create(
 
 		$kirby        = App::instance();
 		$language     = $kirby->defaultLanguage();
-		$translations = $language->translations();
+		$translations = $language->translations()->toArray();
 
 		if ($kirby->translation()->get($key) !== null) {
 			if (isset($translations[$key]) === true) {
@@ -72,11 +72,9 @@ public function delete(): bool
 	{
 		// go through all languages and remove the variable
 		foreach ($this->kirby->languages() as $language) {
-			$variables = $language->translations();
-
-			unset($variables[$this->key]);
-
-			$language->update(['translations' => $variables]);
+			$translations = $language->translations();
+			$translations->remove($this->key);
+			$language->update(['translations' => $translations]);
 		}
 
 		return true;
@@ -88,7 +86,7 @@ public function delete(): bool
 	public function exists(): bool
 	{
 		$language = $this->kirby->defaultLanguage();
-		return isset($language->translations()[$this->key]) === true;
+		return $language->translations()->get($this->key) !== null;
 	}
 
 	/**
@@ -104,8 +102,8 @@ public function key(): string
 	 */
 	public function update(string|null $value = null): static
 	{
-		$translations             = $this->language->translations();
-		$translations[$this->key] = $value ?? '';
+		$translations = $this->language->translations();
+		$translations->set($this->key, $value);
 
 		$language = $this->language->update(['translations' => $translations]);
 
@@ -117,6 +115,6 @@ public function update(string|null $value = null): static
 	 */
 	public function value(): string|null
 	{
-		return $this->language->translations()[$this->key] ?? null;
+		return $this->language->translations()->get($this->key);
 	}
 }

From 437745f5f809ddebd28c5939955d611ea3cb80e6 Mon Sep 17 00:00:00 2001
From: Ahmet Bora <byybora@gmail.com>
Date: Sat, 27 Jan 2024 19:41:11 +0300
Subject: [PATCH 2/6] Apply code reviews

---
 src/Cms/LanguageTranslations.php | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/Cms/LanguageTranslations.php b/src/Cms/LanguageTranslations.php
index 622f60bc2c..6ef7b8fb6f 100644
--- a/src/Cms/LanguageTranslations.php
+++ b/src/Cms/LanguageTranslations.php
@@ -19,14 +19,12 @@
  */
 class LanguageTranslations
 {
-	protected App   $kirby;
 	protected array $data;
 
 	public function __construct(
 		protected Language $language,
 		self|array $translations = []
 	) {
-		$this->kirby = App::instance();
 		$this->setTranslations($translations);
 	}
 
@@ -62,8 +60,9 @@ public function load(array $default = []): array
 	 */
 	public function save(array $translations = []): static
 	{
+		$this->setTranslations($translations);
+
 		if ($root = $this->root()) {
-			$this->data = $translations;
 			Data::write($root, $translations);
 		}
 
@@ -77,7 +76,7 @@ public function root(): string|null
 	{
 		$kirby = App::instance();
 		$root  = $kirby->root('translations');
-		$file  = $root . '/' . $this->language->code() . '.php';
+		$file  = ($root ?? '') . '/' . $this->language->code() . '.php';
 
 		if (
 			$root !== null &&

From b1b372f33d56b7c74e33c1d80e2f0fafdefd5ca8 Mon Sep 17 00:00:00 2001
From: Ahmet Bora <byybora@gmail.com>
Date: Fri, 13 Sep 2024 20:04:18 +0300
Subject: [PATCH 3/6] Improvements

---
 src/Cms/Language.php             | 15 ++----
 src/Cms/LanguageTranslations.php | 81 +++++++++++++++-----------------
 src/Cms/LanguageVariable.php     |  4 +-
 3 files changed, 43 insertions(+), 57 deletions(-)

diff --git a/src/Cms/Language.php b/src/Cms/Language.php
index 26941e1137..9020c89e56 100644
--- a/src/Cms/Language.php
+++ b/src/Cms/Language.php
@@ -236,6 +236,9 @@ public function delete(): bool
 			throw new Exception('The language could not be deleted');
 		}
 
+		// delete custom translations file if defined
+		$language->translations()->delete();
+
 		// if needed, convert content storage to single lang
 		foreach ($kirby->models() as $model) {
 			if ($language->isLast() === true) {
@@ -472,7 +475,6 @@ public function save(): static
 	{
 		try {
 			$existingData = Data::read($this->root());
-			$data['translations'] = $this->translations()->load($existingData['translations'] ?? []);
 		} catch (Throwable) {
 			$existingData = [];
 		}
@@ -588,15 +590,6 @@ public function update(array|null $props = null): static
 		// make sure the slug is nice and clean
 		$props['slug'] = Str::slug($props['slug'] ?? null);
 
-		$kirby   = App::instance();
-		$updated = $this->clone($props);
-
-		if (isset($props['translations']) === true) {
-			$updated->translations = new LanguageTranslations($updated, $props['translations']);
-		}
-
-		// validate the updated language
-		LanguageRules::update($updated);
 
 		// trigger before hook
 		$language = $kirby->apply(
@@ -612,7 +605,7 @@ public function update(array|null $props = null): static
 		$language = $language->clone($props);
 
 		if (isset($props['translations']) === true) {
-			$language->translations = $props['translations'];
+			$language->translations = $language->translations->update($props['translations'] ?? null);
 		}
 
 		// validate the language rules after before hook was applied
diff --git a/src/Cms/LanguageTranslations.php b/src/Cms/LanguageTranslations.php
index 6ef7b8fb6f..32ec0a4950 100644
--- a/src/Cms/LanguageTranslations.php
+++ b/src/Cms/LanguageTranslations.php
@@ -2,13 +2,14 @@
 
 namespace Kirby\Cms;
 
-use Exception;
 use Kirby\Data\Data;
+use Kirby\Exception\Exception;
 use Kirby\Filesystem\F;
+use Throwable;
 
 /**
- * With helper methods provides get language translations or
- * loads from custom `translations` root
+ * Manages the translations string for a language,
+ * either from the language file or `translations` root
  * @since 5.0.0
  *
  * @package   Kirby Cms
@@ -19,51 +20,61 @@
  */
 class LanguageTranslations
 {
-	protected array $data;
-
 	public function __construct(
 		protected Language $language,
-		self|array $translations = []
+		protected array $data = []
 	) {
-		$this->setTranslations($translations);
+		$this->data = [...$this->load(), ...$this->data];
+	}
+
+	/**
+	 * Deletes the current language translations file
+	 * if custom root defined
+	 */
+	public function delete(): void
+	{
+		if ($file = $this->root()) {
+			if (F::remove($file) !== true) {
+				throw new Exception('The language translations could not be deleted');
+			}
+		}
 	}
 
 	/**
 	 * Returns a single translation string by key
 	 */
-	public function get(string $key, string $default = null): string|null
+	public function get(string $key, string|null $default = null): string|null
 	{
 		return $this->data[$key] ?? $default;
 	}
 
 	/**
-	 * Loads the language translations based on custom roots for provided language code
+	 * Loads the language translations based on custom roots
 	 */
-	public function load(array $default = []): array
+	public function load(): array
 	{
 		if ($file = static::root()) {
 			try {
 				return Data::read($file);
-			} catch (Exception) {
-				return $default;
+			} catch (Throwable) {
+				// skip when an exception thrown
 			}
 		}
 
-		return $default;
+		return [];
 	}
 
 	/**
 	 * Saves the language translations in the custom root
-	 * @internal
-	 *
 	 * @return $this
+	 * @internal
 	 */
 	public function save(array $translations = []): static
 	{
-		$this->setTranslations($translations);
+		$this->data = $translations;
 
 		if ($root = $this->root()) {
-			Data::write($root, $translations);
+			Data::write($root, $this->data);
 		}
 
 		return $this;
@@ -74,15 +85,8 @@ public function save(array $translations = []): static
 	 */
 	public function root(): string|null
 	{
-		$kirby = App::instance();
-		$root  = $kirby->root('translations');
-		$file  = ($root ?? '') . '/' . $this->language->code() . '.php';
-
-		if (
-			$root !== null &&
-			F::exists($file) === true
-		) {
-			return $file;
+		if ($root = App::instance()->root('translations')) {
+			return $root . '/' . $this->language->code() . '.php';
 		}
 
 		return null;
@@ -111,30 +115,19 @@ public function set(string $key, string|null $value = null): static
 	}
 
 	/**
-	 * Set translations
-	 *
-	 * @return $this
+	 * Returns translations
 	 */
-	public function setTranslations(self|array $translations = []): static
+	public function toArray(): array
 	{
-		if (empty($translations) === false) {
-			if ($translations instanceof self) {
-				$this->data = $translations->toArray();
-			} else {
-				$this->data = $translations;
-			}
-		} else {
-			$this->data = static::load();
-		}
-
-		return $this;
+		return $this->data;
 	}
 
 	/**
-	 * Returns translations
+	 * Updates the translations data
 	 */
-	public function toArray(): array
+	public function update(array $data = []): static
 	{
-		return $this->data;
+		$this->data = $data;
+		return $this;
 	}
 }
diff --git a/src/Cms/LanguageVariable.php b/src/Cms/LanguageVariable.php
index 6632353eb8..1e9a175ff4 100644
--- a/src/Cms/LanguageVariable.php
+++ b/src/Cms/LanguageVariable.php
@@ -74,7 +74,7 @@ public function delete(): bool
 		foreach ($this->kirby->languages() as $language) {
 			$translations = $language->translations();
 			$translations->remove($this->key);
-			$language->update(['translations' => $translations]);
+			$language->update(['translations' => $translations->toArray()]);
 		}
 
 		return true;
@@ -105,7 +105,7 @@ public function update(string|null $value = null): static
 		$translations = $this->language->translations();
 		$translations->set($this->key, $value);
 
-		$language = $this->language->update(['translations' => $translations]);
+		$language = $this->language->update(['translations' => $translations->toArray()]);
 
 		return $language->variable($this->key);
 	}

From b171903b3639b9209b9d1c93f4bd3d7681162f98 Mon Sep 17 00:00:00 2001
From: Ahmet Bora <byybora@gmail.com>
Date: Mon, 16 Sep 2024 12:33:58 +0300
Subject: [PATCH 4/6] Rename root with `language:variables`

---
 src/Cms/Core.php                 | 55 ++++++++++++++++----------------
 src/Cms/LanguageTranslations.php |  2 +-
 2 files changed, 28 insertions(+), 29 deletions(-)

diff --git a/src/Cms/Core.php b/src/Cms/Core.php
index ee5c8216dc..7446710a67 100644
--- a/src/Cms/Core.php
+++ b/src/Cms/Core.php
@@ -331,34 +331,33 @@ public function load(): Loader
 	public function roots(): array
 	{
 		return $this->cache['roots'] ??= [
-			'kirby'        => fn (array $roots) => dirname(__DIR__, 2),
-			'i18n'         => fn (array $roots) => $roots['kirby'] . '/i18n',
-			'i18n:translations' => fn (array $roots) => $roots['i18n'] . '/translations',
-			'i18n:rules'   => fn (array $roots) => $roots['i18n'] . '/rules',
-
-			'index'        => fn (array $roots) => static::$indexRoot ?? dirname(__DIR__, 3),
-			'assets'       => fn (array $roots) => $roots['index'] . '/assets',
-			'content'      => fn (array $roots) => $roots['index'] . '/content',
-			'media'        => fn (array $roots) => $roots['index'] . '/media',
-			'panel'        => fn (array $roots) => $roots['kirby'] . '/panel',
-			'site'         => fn (array $roots) => $roots['index'] . '/site',
-			'accounts'     => fn (array $roots) => $roots['site'] . '/accounts',
-			'blueprints'   => fn (array $roots) => $roots['site'] . '/blueprints',
-			'cache'        => fn (array $roots) => $roots['site'] . '/cache',
-			'collections'  => fn (array $roots) => $roots['site'] . '/collections',
-			'commands'     => fn (array $roots) => $roots['site'] . '/commands',
-			'config'       => fn (array $roots) => $roots['site'] . '/config',
-			'controllers'  => fn (array $roots) => $roots['site'] . '/controllers',
-			'languages'    => fn (array $roots) => $roots['site'] . '/languages',
-			'license'      => fn (array $roots) => $roots['config'] . '/.license',
-			'logs'         => fn (array $roots) => $roots['site'] . '/logs',
-			'models'       => fn (array $roots) => $roots['site'] . '/models',
-			'plugins'      => fn (array $roots) => $roots['site'] . '/plugins',
-			'roles'        => fn (array $roots) => $roots['blueprints'] . '/users',
-			'sessions'     => fn (array $roots) => $roots['site'] . '/sessions',
-			'snippets'     => fn (array $roots) => $roots['site'] . '/snippets',
-			'templates'    => fn (array $roots) => $roots['site'] . '/templates',
-			'translations' => null,
+			'kirby'              => fn(array $roots) => dirname(__DIR__, 2),
+			'i18n'               => fn(array $roots) => $roots['kirby'] . '/i18n',
+			'i18n:translations'  => fn(array $roots) => $roots['i18n'] . '/translations',
+			'i18n:rules'         => fn(array $roots) => $roots['i18n'] . '/rules',
+			'index'              => fn(array $roots) => static::$indexRoot ?? dirname(__DIR__, 3),
+			'assets'             => fn(array $roots) => $roots['index'] . '/assets',
+			'content'            => fn(array $roots) => $roots['index'] . '/content',
+			'media'              => fn(array $roots) => $roots['index'] . '/media',
+			'panel'              => fn(array $roots) => $roots['kirby'] . '/panel',
+			'site'               => fn(array $roots) => $roots['index'] . '/site',
+			'accounts'           => fn(array $roots) => $roots['site'] . '/accounts',
+			'blueprints'         => fn(array $roots) => $roots['site'] . '/blueprints',
+			'cache'              => fn(array $roots) => $roots['site'] . '/cache',
+			'collections'        => fn(array $roots) => $roots['site'] . '/collections',
+			'commands'           => fn(array $roots) => $roots['site'] . '/commands',
+			'config'             => fn(array $roots) => $roots['site'] . '/config',
+			'controllers'        => fn(array $roots) => $roots['site'] . '/controllers',
+			'language:variables' => null,
+			'languages'          => fn(array $roots) => $roots['site'] . '/languages',
+			'license'            => fn(array $roots) => $roots['config'] . '/.license',
+			'logs'               => fn(array $roots) => $roots['site'] . '/logs',
+			'models'             => fn(array $roots) => $roots['site'] . '/models',
+			'plugins'            => fn(array $roots) => $roots['site'] . '/plugins',
+			'roles'              => fn(array $roots) => $roots['blueprints'] . '/users',
+			'sessions'           => fn(array $roots) => $roots['site'] . '/sessions',
+			'snippets'           => fn(array $roots) => $roots['site'] . '/snippets',
+			'templates'          => fn(array $roots) => $roots['site'] . '/templates',
 		];
 	}
 
diff --git a/src/Cms/LanguageTranslations.php b/src/Cms/LanguageTranslations.php
index 32ec0a4950..a0d8cf431d 100644
--- a/src/Cms/LanguageTranslations.php
+++ b/src/Cms/LanguageTranslations.php
@@ -85,7 +85,7 @@ public function save(array $translations = []): static
 	 */
 	public function root(): string|null
 	{
-		if ($root = App::instance()->root('translations')) {
+		if ($root = App::instance()->root('language:variables')) {
 			return $root . '/' . $this->language->code() . '.php';
 		}
 

From 1628be7c2317a1f85406119bcf876baa99efed84 Mon Sep 17 00:00:00 2001
From: Ahmet Bora <byybora@gmail.com>
Date: Mon, 16 Sep 2024 14:40:45 +0300
Subject: [PATCH 5/6] Swtich from `::translations()` to `::variables()`

---
 config/areas/languages/views.php              |  6 ++--
 src/Cms/AppTranslations.php                   | 12 +++----
 src/Cms/Language.php                          | 35 +++++++++++++------
 src/Cms/LanguageVariable.php                  | 30 ++++++++--------
 ...Translations.php => LanguageVariables.php} | 30 ++++++++--------
 5 files changed, 63 insertions(+), 50 deletions(-)
 rename src/Cms/{LanguageTranslations.php => LanguageVariables.php} (72%)

diff --git a/config/areas/languages/views.php b/config/areas/languages/views.php
index 19d49ec816..b46d058b0e 100644
--- a/config/areas/languages/views.php
+++ b/config/areas/languages/views.php
@@ -17,8 +17,8 @@
 			$language     = Find::language($code);
 			$link         = '/languages/' . $language->code();
 			$strings      = [];
-			$foundation   = $kirby->defaultLanguage()->translations()->toArray();
-			$translations = $language->translations()->toArray();
+			$foundation   = $kirby->defaultLanguage()->variables()->toArray();
+			$variables    = $language->variables()->toArray();
 
 			// TODO: update following line and adapt for update and
 			// delete options when `languageVariables.*` permissions available
@@ -29,7 +29,7 @@
 			foreach ($foundation as $key => $value) {
 				$strings[] = [
 					'key'     => $key,
-					'value'   => $translations[$key] ?? null,
+					'value'   => $variables[$key] ?? null,
 					'options' => [
 						[
 							'click'    => 'update',
diff --git a/src/Cms/AppTranslations.php b/src/Cms/AppTranslations.php
index 1dc6880b04..b2e3fd3293 100644
--- a/src/Cms/AppTranslations.php
+++ b/src/Cms/AppTranslations.php
@@ -33,7 +33,7 @@ protected function i18n(): void
 			) {
 				$data = [
 					...$data,
-					...$language->translations()->toArray()
+					...$language->variables()->toArray()
 				];
 			}
 
@@ -140,7 +140,7 @@ public function translation(string|null $locale = null): Translation
 		if ($language = $this->language($locale)) {
 			$inject = [
 				...$inject,
-				...$language->translations()->toArray()
+				...$language->variables()->toArray()
 			];
 		}
 
@@ -166,14 +166,14 @@ public function translations(): Translations
 		// injects languages translations
 		if ($languages = $this->languages()) {
 			foreach ($languages as $language) {
-				$languageCode         = $language->code();
-				$languageTranslations = $language->translations()->toArray();
+				$languageCode      = $language->code();
+				$languageVariables = $language->variables()->toArray();
 
 				// merges language translations with extensions translations
-				if (empty($languageTranslations) === false) {
+				if (empty($languageVariables) === false) {
 					$translations[$languageCode] = [
 						...$translations[$languageCode] ?? [],
-						...$languageTranslations
+						...$languageVariables
 					];
 				}
 			}
diff --git a/src/Cms/Language.php b/src/Cms/Language.php
index 9020c89e56..dd30026d7e 100644
--- a/src/Cms/Language.php
+++ b/src/Cms/Language.php
@@ -48,8 +48,8 @@ class Language implements Stringable
 	protected bool $single;
 	protected array $slugs;
 	protected array $smartypants;
-	protected LanguageTranslations $translations;
 	protected string|null $url;
+	protected LanguageVariables $variables;
 
 	/**
 	 * Creates a new language object
@@ -76,7 +76,7 @@ public function __construct(array $props)
 			$this->locale = [LC_ALL => $this->code];
 		}
 
-		$this->translations = new LanguageTranslations($this, $props['translations'] ?? []);
+		$this->variables = new LanguageVariables($this, $props['translations'] ?? []);
 	}
 
 	/**
@@ -131,7 +131,7 @@ public function clone(array $props = []): static
 			'name'         => $this->name,
 			'slugs'        => $this->slugs,
 			'smartypants'  => $this->smartypants,
-			'translations' => $this->translations->toArray(),
+			'translations' => $this->variables->toArray(),
 			'url'          => $this->url,
 		], $props));
 	}
@@ -223,6 +223,7 @@ public function delete(): bool
 		LanguageRules::delete($this);
 
 		// apply before hook
+		/** @var \Kirby\Cms\Language $language */
 		$language = $kirby->apply(
 			'language.delete:before',
 			['language' => $this],
@@ -237,7 +238,7 @@ public function delete(): bool
 		}
 
 		// delete custom translations file if defined
-		$language->translations()->delete();
+		$language->variables()->delete();
 
 		// if needed, convert content storage to single lang
 		foreach ($kirby->models() as $model) {
@@ -486,7 +487,7 @@ public function save(): static
 			'direction'    => $this->direction(),
 			'locale'       => Locale::export($this->locale()),
 			'name'         => $this->name(),
-			'translations' => $this->translations()->toArray(),
+			'translations' => $this->variables()->toArray(),
 			'url'          => $this->url,
 		];
 
@@ -494,8 +495,8 @@ public function save(): static
 
 		// save translations to the custom root and remove translations
 		// to prevent duplication write into the language file
-		if ($this->translations()->root() !== null) {
-			$this->translations()->save($data['translations'] ?? []);
+		if ($this->variables()->root() !== null) {
+			$this->variables()->save($data['translations'] ?? []);
 			$data['translations'] = [];
 		}
 
@@ -559,11 +560,14 @@ public function toArray(): array
 	}
 
 	/**
-	 * Returns the language translations object for this language
+	 * Alias for Language::variables()
+	 *
+	 * @deprecated 5.0.0 Use `::variables()` instead
+	 * @todo 7.0.0 Remove the method
 	 */
-	public function translations(): LanguageTranslations
+	public function translations(): LanguageVariables
 	{
-		return $this->translations;
+		return $this->variables();
 	}
 
 	/**
@@ -592,6 +596,7 @@ public function update(array|null $props = null): static
 
 
 		// trigger before hook
+		/** @var \Kirby\Cms\Language $language */
 		$language = $kirby->apply(
 			'language.update:before',
 			[
@@ -605,7 +610,7 @@ public function update(array|null $props = null): static
 		$language = $language->clone($props);
 
 		if (isset($props['translations']) === true) {
-			$language->translations = $language->translations->update($props['translations'] ?? null);
+			$language->variables = $language->variables->update($props['translations'] ?? null);
 		}
 
 		// validate the language rules after before hook was applied
@@ -655,4 +660,12 @@ public function variable(string $key, bool $decode = false): LanguageVariable
 
 		return new LanguageVariable($this, $key);
 	}
+
+	/**
+	 * Returns the language variables object for this language
+	 */
+	public function variables(): LanguageVariables
+	{
+		return $this->variables;
+	}
 }
diff --git a/src/Cms/LanguageVariable.php b/src/Cms/LanguageVariable.php
index 1e9a175ff4..d0d941ed2d 100644
--- a/src/Cms/LanguageVariable.php
+++ b/src/Cms/LanguageVariable.php
@@ -44,21 +44,21 @@ public static function create(
 			throw new InvalidArgumentException('The variable needs a valid key');
 		}
 
-		$kirby        = App::instance();
-		$language     = $kirby->defaultLanguage();
-		$translations = $language->translations()->toArray();
+		$kirby     = App::instance();
+		$language  = $kirby->defaultLanguage();
+		$variables = $language->variables()->toArray();
 
 		if ($kirby->translation()->get($key) !== null) {
-			if (isset($translations[$key]) === true) {
+			if (isset($variables[$key]) === true) {
 				throw new DuplicateException('The variable already exists');
 			}
 
 			throw new DuplicateException('The variable is part of the core translation and cannot be overwritten');
 		}
 
-		$translations[$key] = $value ?? '';
+		$variables[$key] = $value ?? '';
 
-		$language->update(['translations' => $translations]);
+		$language->update(['variables' => $variables]);
 
 		return $language->variable($key);
 	}
@@ -72,9 +72,9 @@ public function delete(): bool
 	{
 		// go through all languages and remove the variable
 		foreach ($this->kirby->languages() as $language) {
-			$translations = $language->translations();
-			$translations->remove($this->key);
-			$language->update(['translations' => $translations->toArray()]);
+			$variables = $language->variables();
+			$variables->remove($this->key);
+			$language->update(['variables' => $variables->toArray()]);
 		}
 
 		return true;
@@ -86,7 +86,7 @@ public function delete(): bool
 	public function exists(): bool
 	{
 		$language = $this->kirby->defaultLanguage();
-		return $language->translations()->get($this->key) !== null;
+		return $language->variables()->get($this->key) !== null;
 	}
 
 	/**
@@ -102,19 +102,19 @@ public function key(): string
 	 */
 	public function update(string|null $value = null): static
 	{
-		$translations = $this->language->translations();
-		$translations->set($this->key, $value);
+		$variables = $this->language->variables();
+		$variables->set($this->key, $value);
 
-		$language = $this->language->update(['translations' => $translations->toArray()]);
+		$language = $this->language->update(['variables' => $variables->toArray()]);
 
 		return $language->variable($this->key);
 	}
 
 	/**
-	 * Returns the value if the variable has been translated.
+	 * Returns the value if the variable has been translated
 	 */
 	public function value(): string|null
 	{
-		return $this->language->translations()->get($this->key);
+		return $this->language->variables()->get($this->key);
 	}
 }
diff --git a/src/Cms/LanguageTranslations.php b/src/Cms/LanguageVariables.php
similarity index 72%
rename from src/Cms/LanguageTranslations.php
rename to src/Cms/LanguageVariables.php
index a0d8cf431d..e214546b18 100644
--- a/src/Cms/LanguageTranslations.php
+++ b/src/Cms/LanguageVariables.php
@@ -8,8 +8,8 @@
 use Throwable;
 
 /**
- * Manages the translations string for a language,
- * either from the language file or `translations` root
+ * Manages the variables string for a language,
+ * either from the language file or `language:variables` root
  * @since 5.0.0
  *
  * @package   Kirby Cms
@@ -18,7 +18,7 @@
  * @copyright Bastian Allgeier
  * @license   https://getkirby.com/license
  */
-class LanguageTranslations
+class LanguageVariables
 {
 	public function __construct(
 		protected Language $language,
@@ -28,20 +28,20 @@ public function __construct(
 	}
 
 	/**
-	 * Deletes the current language translations file
+	 * Deletes the current language variables file
 	 * if custom root defined
 	 */
 	public function delete(): void
 	{
 		if ($file = $this->root()) {
 			if (F::remove($file) !== true) {
-				throw new Exception('The language translations could not be deleted');
+				throw new Exception('The language variables could not be deleted');
 			}
 		}
 	}
 
 	/**
-	 * Returns a single translation string by key
+	 * Returns a single variable string by key
 	 */
 	public function get(string $key, string|null $default = null): string|null
 	{
@@ -49,7 +49,7 @@ public function get(string $key, string|null $default = null): string|null
 	}
 
 	/**
-	 * Loads the language translations based on custom roots
+	 * Loads the language variables based on custom roots
 	 */
 	public function load(): array
 	{
@@ -65,13 +65,13 @@ public function load(): array
 	}
 
 	/**
-	 * Saves the language translations in the custom root
+	 * Saves the language variables in the custom root
 	 * @return $this
 	 * @internal
 	 */
-	public function save(array $translations = []): static
+	public function save(array $variables = []): static
 	{
-		$this->data = $translations;
+		$this->data = $variables;
 
 		if ($root = $this->root()) {
 			Data::write($root, $this->data);
@@ -81,7 +81,7 @@ public function save(array $translations = []): static
 	}
 
 	/**
-	 * Returns custom translations root path if defined
+	 * Returns custom variables root path if defined
 	 */
 	public function root(): string|null
 	{
@@ -93,7 +93,7 @@ public function root(): string|null
 	}
 
 	/**
-	 * Removes a translation key
+	 * Removes a variable key
 	 *
 	 * @return $this
 	 */
@@ -104,7 +104,7 @@ public function remove(string $key): static
 	}
 
 	/**
-	 * Sets the translation key
+	 * Sets the variable key
 	 *
 	 * @return $this
 	 */
@@ -115,7 +115,7 @@ public function set(string $key, string|null $value = null): static
 	}
 
 	/**
-	 * Returns translations
+	 * Returns variables
 	 */
 	public function toArray(): array
 	{
@@ -123,7 +123,7 @@ public function toArray(): array
 	}
 
 	/**
-	 * Updates the translations data
+	 * Updates the variables data
 	 */
 	public function update(array $data = []): static
 	{

From b56dad65b927118032e38ccb4c4e423ab30b76f3 Mon Sep 17 00:00:00 2001
From: Ahmet Bora <byybora@gmail.com>
Date: Wed, 13 Nov 2024 22:21:43 +0300
Subject: [PATCH 6/6] Apply suggestions from code review

Co-authored-by: Bastian Allgeier <mail@bastianallgeier.com>
---
 src/Cms/Language.php | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/Cms/Language.php b/src/Cms/Language.php
index dd30026d7e..c4dfbb3aa6 100644
--- a/src/Cms/Language.php
+++ b/src/Cms/Language.php
@@ -76,7 +76,7 @@ public function __construct(array $props)
 			$this->locale = [LC_ALL => $this->code];
 		}
 
-		$this->variables = new LanguageVariables($this, $props['translations'] ?? []);
+		$this->variables = new LanguageVariables($this, $props['variables'] ?? $props['translations'] ?? []);
 	}
 
 	/**
@@ -131,7 +131,7 @@ public function clone(array $props = []): static
 			'name'         => $this->name,
 			'slugs'        => $this->slugs,
 			'smartypants'  => $this->smartypants,
-			'translations' => $this->variables->toArray(),
+			'variables' => $this->variables->toArray(),
 			'url'          => $this->url,
 		], $props));
 	}
@@ -487,7 +487,7 @@ public function save(): static
 			'direction'    => $this->direction(),
 			'locale'       => Locale::export($this->locale()),
 			'name'         => $this->name(),
-			'translations' => $this->variables()->toArray(),
+			'variables' => $this->variables()->toArray(),
 			'url'          => $this->url,
 		];