Skip to content

Commit

Permalink
core(translate) : Improve translate class PHPDoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@kwizer15
kwizer15 committed Feb 5, 2025
1 parent 7d52c06 commit 8af153c
Showing 1 changed file with 104 additions and 0 deletions.
104 changes: 104 additions & 0 deletions core/class/translate.class.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,17 +35,43 @@
//log::add('debug_translate', 'error', $_content);
*/

/**
* Handles internationalization (i18n) for Jeedom system
*
* Provides translation capabilities for both core system and plugins,
* with caching mechanisms for better performance.
*
* @see config For language configuration
* @see plugin For plugin-related translations
*/
class translate {
/* * *************************Attributs****************************** */

/** @var array<string, array<string, array<string, string>>> Cached translations by language and namespace */
protected static $translation = array();

/** @var string|null Current active language */
protected static $language = null;

/** @var array<string, string>|null System configuration cache */
private static $config = null;

/** @var array<string, bool> Loaded plugins tracking */
private static $pluginLoad = array();

/** @var array<string, array<string, array<string, string>>> Loaded widgets translations */
private static $widgetLoad = array();

/* * ***********************Methode static*************************** */

/**
* Retrieves a configuration value
*
* @param string $_key Configuration key to retrieve
* @param string $_default Default value if key not found
* @return string Configuration value
* @see config::byKeys() For configuration retrieval
*/
public static function getConfig($_key, $_default = '') {
if (self::$config === null) {
self::$config = config::byKeys(array('language'));
Expand All @@ -56,6 +82,12 @@ public static function getConfig($_key, $_default = '') {
return $_default;
}

/**
* Gets translations for a plugin
*
* @param string $_plugin Plugin identifier
* @return array<string, array<string, string>> Translation mappings
*/
public static function getTranslation($_plugin) {
if (!isset(self::$translation[self::getLanguage()])) {
self::$translation[self::getLanguage()] = array();
Expand All @@ -67,6 +99,12 @@ public static function getTranslation($_plugin) {
return self::$translation[self::getLanguage()];
}

/**
* Gets translations for a widget
*
* @param string $_widget Widget identifier
* @return array<string, array<string, string>> Translation mappings
*/
public static function getWidgetTranslation($_widget) {
if (!isset(self::$translation[self::getLanguage()]['core/template/widgets.html'])) {
self::$translation[self::getLanguage()]['core/template/widgets.html'] = array();
Expand All @@ -77,10 +115,25 @@ public static function getWidgetTranslation($_widget) {
return self::$widgetLoad[$_widget];
}

/**
* Translates a single text key
*
* @param string $_content Translation key
* @param string $_name Plugin/widget identifier or path
* @param bool $_backslash Whether to escape single quotes
* @return string Translated text
* @see self::exec() For full translation processing
*/
public static function sentence($_content, $_name, $_backslash = false) {
return self::exec("{{" . $_content . "}}", $_name, $_backslash);
}

/**
* Extracts plugin name from file path
*
* @param string $_name File path
* @return string Plugin name or 'core'
*/
public static function getPluginFromName($_name) {
if (strpos($_name, 'plugins/') === false) {
return 'core';
Expand All @@ -95,6 +148,17 @@ public static function getPluginFromName($_name) {
return $matches[1];
}

/**
* Processes text content for internationalization
*
* @param string $_content Text with {{translation_keys}}
* @param string $_name Plugin/widget identifier or path
* @param bool $_backslash Whether to escape single quotes
* @return string Translated content
* @see self::getLanguage() For current language
* @see self::getTranslation() For plugin translations
* @see self::getWidgetTranslation() For widget translations
*/
public static function exec($_content, $_name = '', $_backslash = false) {
if ($_content == '' || $_name == '') {
return $_content;
Expand Down Expand Up @@ -163,14 +227,34 @@ public static function exec($_content, $_name = '', $_backslash = false) {
return str_replace(array_keys($replace), $replace, $_content);
}

/**
* Returns path to language translation file
*
* @param string $_language Language code
* @return string File path
*/
public static function getPathTranslationFile($_language) {
return __DIR__ . '/../i18n/' . $_language . '.json';
}


/**
* Returns path to widget translation file
*
* @param string $_widgetName Widget name
* @return string File path
*/
public static function getWidgetPathTranslationFile($_widgetName) {
return __DIR__ . '/../../data/customTemplates/i18n/' . $_widgetName . '.json';
}

/**
* Loads translations for core or plugin
*
* @param string|null $_plugin Plugin name or null for core
* @return array<string, array<string, string>> Translation mappings
* @see plugin::getTranslation() For plugin translations
*/
public static function loadTranslation($_plugin = null) {
$return = array();
if ($_plugin == null || $_plugin == 'core') {
Expand Down Expand Up @@ -202,20 +286,40 @@ public static function loadTranslation($_plugin = null) {
return $return;
}

/**
* Gets current active language
*
* @return string Language code
*/
public static function getLanguage() {
if (self::$language == null) {
self::$language = self::getConfig('language', 'fr_FR');
}
return self::$language;
}

/**
* Sets active language
*
* @param string $_langage Language code
* @return void
*/
public static function setLanguage($_langage) {
self::$language = $_langage;
}

/* * *********************Methode d'instance************************* */
}

/**
* Global translation helper for a single text key
*
* @param string $_content Translation key
* @param string $_name Plugin/widget identifier or path
* @param bool $_backslash Whether to escape single quotes
* @return string Translated text
* @see translate::sentence() Core translation method
*/
function __($_content, $_name, $_backslash = false) {
return translate::sentence(str_replace("\'", "'", $_content), $_name, $_backslash);
}

0 comments on commit 8af153c

Please sign in to comment.