ilPluginLanguage Class Reference

Collaboration diagram for ilPluginLanguage:

Public Member Functions
	__construct (ilPluginInfo $plugin_info)
	getAvailableLangFiles ()
	Get array of all language files in the plugin. More...
	hasAvailableLangFiles ()
	getPrefix ()
	updateLanguages (?array $a_lang_keys=null)
	uninstall ()
	loadLanguageModule ()
	Load language module for plugin. More...
	txt (string $a_var)
	Get Language Variable (prefix will be prepended automatically) More...

Protected Member Functions
	getLanguageDirectory ()

Protected Attributes
ilPluginInfo	$plugin_info

Private Member Functions
	readLangFile (string $file)
	Key (without the plugin prefix) => value. More...
	logShippedViolations (string $file, array $values)
	Logs every value with disallowed markup, changes nothing. More...
	cleanShippedValues (string $file, array $values)
	Removes disallowed markup and logs what was removed. More...
	readPoFile (string $file)
	Key (msgid, without the plugin prefix) => value, null if the file cannot be read (logged, the update goes on with the other languages). More...

Static Private Member Functions
static	logWarning (string $message)
	Falls back to the PHP error log (e.g. More...

Detailed Description

Author

Richard Klees richa.nosp@m.rd.k.nosp@m.lees@.nosp@m.conc.nosp@m.epts-.nosp@m.and-.nosp@m.train.nosp@m.ing..nosp@m.de

Definition at line 32 of file class.ilPluginLanguage.php.

Constructor & Destructor Documentation

__construct()

ilPluginLanguage::__construct

(

ilPluginInfo

$plugin_info

)

Definition at line 36 of file class.ilPluginLanguage.php.

    {
        $this->plugin_info = $plugin_info;
    }

References $plugin_info.

Member Function Documentation

cleanShippedValues()

ilPluginLanguage::cleanShippedValues ( string  $file, array  $values  )

private

Removes disallowed markup and logs what was removed.

Parameters

array<string,string>

$values key => value

Returns

array<string, string>

Definition at line 202 of file class.ilPluginLanguage.php.

                                                                    : array
    {
        $policy = new TranslationMarkupPolicy();
        foreach ($policy->findInvalidValues($values) as $key => $violations) {
            $values[$key] = $policy->sanitize($values[$key]);
            self::logWarning(sprintf(
                'Markup not allowed in a language value, %s (key "%s"): removed %s',
                $file,
                $key,
                implode(', ', $violations)
            ));
        }
 
        return $values;
    }

References $policy, and logWarning().

Referenced by readPoFile().

Here is the call graph for this function:

Here is the caller graph for this function:

getAvailableLangFiles()

ilPluginLanguage::getAvailableLangFiles

(

)

Get array of all language files in the plugin.

A language may be shipped as ilias_<lang>.po instead of .lang (see readPoFile()); if both exist, the .po is used.

Returns

array of [key => "en" (e.g.), file => ...]

Definition at line 53 of file class.ilPluginLanguage.php.

                                           : array
    {
        $directory = $this->getLanguageDirectory();
        if (!@is_dir($directory)) {
            return [];
        }
 
        $lang_files = [];
        $po_files = [];
 
        $dir = opendir($directory);
        while ($file = readdir($dir)) {
            if ($file === "." || $file === "..") {
                continue;
            }
 
            // directories
            if (!@is_file($directory . "/" . $file)) {
                continue;
            }
            if (strpos($file, "ilias_") === 0 && substr($file, strlen($file) - 5) === ".lang") {
                $lang_files[substr($file, 6, 2)] = [
                    "key" => substr($file, 6, 2),
                    "file" => $file
                ];
            } elseif (preg_match('/\Ailias_([a-z]{2})\.po\z/', $file, $matches) === 1) {
                $po_files[$matches[1]] = [
                    "key" => $matches[1],
                    "file" => $file
                ];
            }
        }
        closedir($dir);
 
        return array_values(array_replace($lang_files, $po_files));
    }

References $lang_files, and getLanguageDirectory().

Referenced by hasAvailableLangFiles(), and updateLanguages().

Here is the call graph for this function:

Here is the caller graph for this function:

getLanguageDirectory()

ilPluginLanguage::getLanguageDirectory ( )

protected

Definition at line 41 of file class.ilPluginLanguage.php.

                                             : string
    {
        return $this->plugin_info->getPath() . "/lang";
    }

Referenced by getAvailableLangFiles(), and updateLanguages().

Here is the caller graph for this function:

getPrefix()

ilPluginLanguage::getPrefix

(

)

Definition at line 95 of file class.ilPluginLanguage.php.

                               : string
    {
        $plugin = $this->plugin_info;
        $component = $plugin->getComponent();
        $slot = $plugin->getPluginSlot();
 
        return $component->getId() . "_" . $slot->getId() . "_" . $plugin->getId();
    }

References XapiProxy\$plugin, and $plugin_info.

Referenced by loadLanguageModule(), txt(), uninstall(), and updateLanguages().

Here is the caller graph for this function:

hasAvailableLangFiles()

ilPluginLanguage::hasAvailableLangFiles

(

)

Definition at line 90 of file class.ilPluginLanguage.php.

                                           : bool
    {
        return count($this->getAvailableLangFiles()) > 0;
    }

References getAvailableLangFiles().

Here is the call graph for this function:

loadLanguageModule()

ilPluginLanguage::loadLanguageModule

(

)

Load language module for plugin.

Definition at line 368 of file class.ilPluginLanguage.php.

                                        : void
    {
        global $DIC;
        $lng = $DIC->language();
 
        if (is_object($lng)) {
            $lng->loadLanguageModule($this->getPrefix());
        }
    }

References $DIC, $lng, and getPrefix().

Referenced by txt().

Here is the call graph for this function:

Here is the caller graph for this function:

logShippedViolations()

ilPluginLanguage::logShippedViolations ( string  $file, array  $values  )

private

Logs every value with disallowed markup, changes nothing.

Parameters

array<string,string>

$values key => value

Definition at line 184 of file class.ilPluginLanguage.php.

                                                                      : void
    {
        foreach ((new TranslationMarkupPolicy())->findInvalidValues($values) as $key => $violations) {
            self::logWarning(sprintf(
                'Markup not allowed in a language value, %s (key "%s"), taken over unchanged: %s',
                $file,
                $key,
                implode(', ', $violations)
            ));
        }
    }

References logWarning().

Referenced by readLangFile().

Here is the call graph for this function:

Here is the caller graph for this function:

logWarning()

static ilPluginLanguage::logWarning ( string  $message )

staticprivate

Falls back to the PHP error log (e.g.

in Setup): a plugin language update must not fail because it cannot log.

Definition at line 288 of file class.ilPluginLanguage.php.

                                                       : void
    {
        global $DIC;
        $message = PlainLogText::of($message);
        try {
            $DIC->logger()->forComponent('lang')->warning($message);
        } catch (\Throwable) {
            error_log($message);
        }
    }

References $DIC, and $message.

Referenced by cleanShippedValues(), logShippedViolations(), and readPoFile().

Here is the caller graph for this function:

readLangFile()

ilPluginLanguage::readLangFile ( string  $file )

private

Key (without the plugin prefix) => value.

Disallowed markup is only logged (see logShippedViolations()), unlike for a .po (see readPoFile()), whose values are cleaned.

Returns

array<string, string>

Definition at line 161 of file class.ilPluginLanguage.php.

                                               : array
    {
        $values = [];
        $txt = file($file);
        if (is_array($txt)) {
            foreach ($txt as $row) {
                if ($row[0] !== "#" && strpos($row, "#:#") > 0) {
                    $a = explode("#:#", trim($row));
                    $values[trim($a[0])] = trim($a[1]);
                }
            }
        }
 
        $this->logShippedViolations($file, $values);
 
        return $values;
    }

References Vendor\Package\$a, and logShippedViolations().

Referenced by updateLanguages().

Here is the call graph for this function:

Here is the caller graph for this function:

readPoFile()

ilPluginLanguage::readPoFile ( string  $file )

private

Key (msgid, without the plugin prefix) => value, null if the file cannot be read (logged, the update goes on with the other languages).

Only entries without msgctxt are read: the file belongs to the plugin's module, whose name (the prefix) must not appear in it, as it changes when the plugin becomes a component. Entries with a msgctxt, even an empty one, are ignored and logged. Disallowed markup is cleaned (and logged) like the build does for a component's shipped .po. Extracted comments are not stored. Fuzzy entries are read, untranslated ones not. A plural message is read with its default form (see PluralForms) and logged: plugins are served from the database, which holds one value per key.

Returns

array<string, string>|null

Definition at line 231 of file class.ilPluginLanguage.php.

                                             : ?array
    {
        try {
            $catalog = TranslationCatalog::fromPoFile($file);
        } catch (\RuntimeException $e) {
            self::logWarning(sprintf(
                'The plugin language file "%s" cannot be read - this language of the plugin is not updated: %s',
                $file,
                $e->getMessage()
            ));
            return null;
        }
 
        $values = [];
        $ignored = [];
        $plurals = [];
        $plural_forms = null;
        foreach ($catalog->getEntries() as $entry) {
            if ($entry->getContext() !== null) {
                $ignored[] = $entry->getId();
                continue;
            }
            $value = $entry->getTranslation();
            if ($entry->isPlural()) {
                $plural_forms ??= PluralForms::fromHeaderOrGermanic(
                    $catalog->getHeader('Plural-Forms'),
                    static fn(string $message) => self::logWarning(sprintf('Plugin language file "%s": %s', $file, $message))
                );
                $value = $plural_forms->defaultValueOf($entry->getPluralTranslations());
                $plurals[] = $entry->getId();
            }
            if ($value !== '') {
                $values[$entry->getId()] = $value;
            }
        }
        if ($plurals !== []) {
            self::logWarning(sprintf(
                'Plural messages in the plugin language file "%s" are stored with their default form only (plugins are served from the database): %s',
                $file,
                implode(', ', $plurals)
            ));
        }
        $values = $this->cleanShippedValues($file, $values);
        if ($ignored !== []) {
            self::logWarning(sprintf(
                'Entries with a msgctxt in the plugin language file "%s" are ignored (a plugin .po has none): %s',
                $file,
                implode(', ', $ignored)
            ));
        }
 
        return $values;
    }

References Vendor\Package\$e, $message, cleanShippedValues(), and logWarning().

Referenced by updateLanguages().

Here is the call graph for this function:

Here is the caller graph for this function:

txt()

ilPluginLanguage::txt

(

string

$a_var

)

Get Language Variable (prefix will be prepended automatically)

Definition at line 381 of file class.ilPluginLanguage.php.

                                      : string
    {
        global $DIC;
        $lng = $DIC->language();
        $this->loadLanguageModule();
 
        $key = $this->getPrefix() . "_" . $a_var;
        $text = $lng->txt($key);
        if ($text !== "-" . $key . "-" || !$lng instanceof ilLanguage) {
            return $text;
        }
 
        // plugin language files are often incomplete: the default language fills the gap, as before
        return ilLanguage::_lookupEntry($lng->getDefaultLanguage(), $this->getPrefix(), $key);
    }

References $DIC, $lng, $text, ilLanguage\_lookupEntry(), getPrefix(), and loadLanguageModule().

Here is the call graph for this function:

uninstall()

ilPluginLanguage::uninstall

(

)

Definition at line 299 of file class.ilPluginLanguage.php.

                               : void
    {
        global $DIC;
        $ilDB = $DIC->database();
 
        // remove all language entries (see ilObjLanguage)
        // see updateLanguages
        $prefix = $this->getPrefix();
        if ($prefix) {
            $ilDB->manipulate(
                "DELETE FROM lng_data" .
                " WHERE module = " . $ilDB->quote($prefix, "text")
            );
            $ilDB->manipulate(
                "DELETE FROM lng_modules" .
                " WHERE module = " . $ilDB->quote($prefix, "text")
            );
 
            $this->removeMigratedMoFiles($prefix);
        }
    }

References $DIC, $ilDB, and getPrefix().

Here is the call graph for this function:

updateLanguages()

ilPluginLanguage::updateLanguages

(

?array

$a_lang_keys = null

)

Definition at line 109 of file class.ilPluginLanguage.php.

                                                               : void
    {
        // get the keys of all installed languages if keys are not provided
        if (!isset($a_lang_keys)) {
            $a_lang_keys = ilObjLanguage::getLangKeysOfInstalledLanguages();
        }
 
        $langs = $this->getAvailableLangFiles();
 
        $prefix = $this->getPrefix();
 
        foreach ($langs as $lang) {
            // check if the language should be updated, otherwise skip it
            if (!in_array($lang['key'], $a_lang_keys, true)) {
                continue;
            }
 
            $file = $this->getLanguageDirectory() . "/" . $lang["file"];
            $values = str_ends_with($lang["file"], ".po") ? $this->readPoFile($file) : $this->readLangFile($file);
            if ($values === null) {
                // a broken .po: this language of the plugin is left as it is (logged)
                continue;
            }
            $lang_array = [];
 
            // get locally changed variables of the module (these should be kept)
            $local_changes = ilObjLanguage::_getLocalChangesByModule($lang['key'], $prefix);
 
            foreach ($values as $key => $value) {
                $identifier = $prefix . "_" . $key;
 
                if (isset($local_changes[$identifier])) {
                    $lang_array[$identifier] = $local_changes[$identifier];
                } else {
                    $lang_array[$identifier] = $value;
                    ilObjLanguage::replaceLangEntry($prefix, $identifier, $lang["key"], $value);
                }
            }
 
            // $refresh_original_from_shipped: the content is the plugin's own shipped file, like a core component update.
            // No overlay is written yet: a plugin cannot contribute a LanguageFileDirectory (the component graph is
            // built from components/ only), a plugin .po goes into the database only.
            ilObjLanguage::replaceLangModule($lang["key"], $prefix, $lang_array, true);
        }
    }

References ilObjLanguage\_getLocalChangesByModule(), getAvailableLangFiles(), ilObjLanguage\getLangKeysOfInstalledLanguages(), getLanguageDirectory(), getPrefix(), readLangFile(), readPoFile(), ilObjLanguage\replaceLangEntry(), and ilObjLanguage\replaceLangModule().

Here is the call graph for this function:

Field Documentation

$plugin_info

ilPluginInfo ilPluginLanguage::$plugin_info

protected

Definition at line 34 of file class.ilPluginLanguage.php.

Referenced by __construct(), and getPrefix().

---

The documentation for this class was generated from the following file:

• components/ILIAS/Language/classes/class.ilPluginLanguage.php