ILIAS\Language\ComponentTranslation\TranslationGettextRepository Class Reference

TranslationRepository over the build (ShippedTranslationsBuild) with the overlay of local changes (MigratedLanguageFileSync) on top, looked up via native gettext (NativeGettext), never via the gettext/gettext library or lng_data/lng_modules. More...

Inheritance diagram for ILIAS\Language\ComponentTranslation\TranslationGettextRepository:

Collaboration diagram for ILIAS\Language\ComponentTranslation\TranslationGettextRepository:

Public Member Functions
	getKeys (string $module, string $lang_key, ?string $client_data_dir)
	Identifier => $module, null if $module is not served for $lang_key. More...
	getText (string $module, string $lang_key, string $key, ?string $client_data_dir)
	null if there is none (not served, not translated, or a problem, see MigratedTranslations::getProblem()). More...
	getPluralText (string $module, string $lang_key, string $key, int $n, ?string $client_data_dir)
	Also null if the overlay holds a singular value for $key or where getText() returns null. More...
	invalidateModule (string $module, string $lang_key)
	Forgets what was read for $module/$lang_key, so a local change just written is served. More...
	invalidateLanguage (string $lang_key)
	Forgets what was read for $lang_key (e.g. More...
	invalidateAll ()
	Forgets everything read so far, see MigratedTranslations::reset(). More...
	getKeys (string $module, string $lang_key, ?string $client_data_dir)
	Identifier => $module, null if $module is not served for $lang_key. More...
	getText (string $module, string $lang_key, string $key, ?string $client_data_dir)
	null if there is none (not served, not translated, or a problem, see MigratedTranslations::getProblem()). More...
	getPluralText (string $module, string $lang_key, string $key, int $n, ?string $client_data_dir)
	The form the plural rule of $lang_key selects for $n; null if $key is no plural message there. More...

Static Private Member Functions
static	servedState (string $module, string $lang_key, string $key, ?string $client_data_dir)
	The state of $module/$lang_key if it is readable and lists the identifier $key, null otherwise. More...
static	state (string $module, string $lang_key, ?string $client_data_dir)
static	withOverlay (array $state, string $client_data_dir, string $module, string $lang_key)
	$state with the overlay revision current of the overlay of $module/$lang_key names, if any. More...
static	lookup (string $domain, string $message_id)
	The translation of $message_id in. More...
static	reportLostActivation ()
static	hasSymbolicLink (array $paths)
static	readStart (string $file, int $length)
	At most the first $length bytes of $file, null if it cannot be read. More...
static	buildKeys (string $build_directory, string $module)

Private Attributes
const int	MAX_REVISION_FILE_SIZE = 128
	current only holds the name of a revision - more is never read. More...

Static Private Attributes
static array	$build_keys = []
static array	$states = []

Detailed Description

TranslationRepository over the build (ShippedTranslationsBuild) with the overlay of local changes (MigratedLanguageFileSync) on top, looked up via native gettext (NativeGettext), never via the gettext/gettext library or lng_data/lng_modules.

A module is served for a language if the build in artifacts/language/current.json (with a system locale current-system.json) was built for it. On first use per module and language in a request (getKeys()):

• native gettext is activated with the build's locale, the domain "<module>.<lang>" bound to the build and, if <client data dir>/lang/<module>/<lang>/current names a revision, "<module>.<lang>.overlay" to it;
• the identifiers are those of the build's keys/<module>.php plus the overlay revision's keys.json. getText() looks an identifier of the overlay up in the overlay domain, every other in the build's.

Problems (no build, no native gettext, an unreadable catalog) go to MigratedTranslations::reportProblem(); identifiers of the module concerned are not found then. An unreadable overlay is reported and left out: the shipped values are served.

The state is static, as the domains are bound per process.

@phpstan-type State array{keys: array<string, string>, ok: bool, domain: string, overlay_domain: ?string, overlay_keys: array<string, true>, overlay_checked: bool}

Definition at line 43 of file TranslationGettextRepository.php.

Member Function Documentation

buildKeys()

static ILIAS\Language\ComponentTranslation\TranslationGettextRepository::buildKeys ( string  $build_directory, string  $module  )

staticprivate

Returns

array<string, string>|null

Definition at line 325 of file TranslationGettextRepository.php.

                                                                              : ?array
    {
        if (!array_key_exists($module, self::$build_keys)) {
            $file = MigratedLanguageFilePaths::buildKeysFile($build_directory, $module);
            $keys = is_file($file) ? (static fn(string $file): mixed => include $file)($file) : null;
            self::$build_keys[$module] = is_array($keys) ? $keys : null;
        }
 
        return self::$build_keys[$module];
    }

References $module, and ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\buildKeysFile().

Referenced by ILIAS\Language\ComponentTranslation\TranslationGettextRepository\state().

Here is the call graph for this function:

Here is the caller graph for this function:

getKeys()

ILIAS\Language\ComponentTranslation\TranslationGettextRepository::getKeys	(	string	$module,
		string	$lang_key,
		?string	$client_data_dir
	)

Identifier => $module, null if $module is not served for $lang_key.

Parameters

string | null

$client_data_dir

where the local changes are looked up, none without

Returns

array<string, string>|null

Implements ILIAS\Language\ComponentTranslation\TranslationRepository.

Definition at line 64 of file TranslationGettextRepository.php.

                                                                                       : ?array
    {
        return self::state($module, $lang_key, $client_data_dir)['keys'] ?? null;
    }

References $module, and ILIAS\Language\ComponentTranslation\TranslationGettextRepository\state().

Here is the call graph for this function:

getPluralText()

ILIAS\Language\ComponentTranslation\TranslationGettextRepository::getPluralText	(	string	$module,
		string	$lang_key,
		string	$key,
		int	$n,
		?string	$client_data_dir
	)

Also null if the overlay holds a singular value for $key or where getText() returns null.

Implements ILIAS\Language\ComponentTranslation\TranslationRepository.

Definition at line 92 of file TranslationGettextRepository.php.

                                                                                                                  : ?string
    {
        $state = self::servedState($module, $lang_key, $key, $client_data_dir);
        if ($state === null) {
            return null;
        }
        $domain = $state['overlay_domain'] !== null && isset($state['overlay_keys'][$key])
            ? $state['overlay_domain']
            : $state['domain'];
        $message_id = ShippedTranslations::PLURAL_CONTEXT . "\x04" . $key;
        $value = NativeGettext::translatePlural($domain, $message_id, $n);
        if ($value === $message_id && !NativeGettext::isActive()) {
            if (!NativeGettext::reactivateIfLost()) {
                self::reportLostActivation();
                return null;
            }
            $value = NativeGettext::translatePlural($domain, $message_id, $n);
        }
 
        return $value === $message_id ? null : $value;
    }

References $module, ILIAS\Language\ComponentTranslation\NativeGettext\isActive(), ILIAS\Language\ComponentTranslation\ShippedTranslations\PLURAL_CONTEXT, ILIAS\Language\ComponentTranslation\NativeGettext\reactivateIfLost(), ILIAS\Language\ComponentTranslation\TranslationGettextRepository\reportLostActivation(), ILIAS\Language\ComponentTranslation\TranslationGettextRepository\servedState(), and ILIAS\Language\ComponentTranslation\NativeGettext\translatePlural().

Here is the call graph for this function:

getText()

ILIAS\Language\ComponentTranslation\TranslationGettextRepository::getText	(	string	$module,
		string	$lang_key,
		string	$key,
		?string	$client_data_dir
	)

null if there is none (not served, not translated, or a problem, see MigratedTranslations::getProblem()).

Implements ILIAS\Language\ComponentTranslation\TranslationRepository.

Definition at line 69 of file TranslationGettextRepository.php.

                                                                                                    : ?string
    {
        $state = self::servedState($module, $lang_key, $key, $client_data_dir);
        if ($state === null) {
            return null;
        }
        if ($state['overlay_domain'] !== null && isset($state['overlay_keys'][$key])) {
            // listed in the overlay: a value equal to the identifier is a value as well
            $value = self::lookup($state['overlay_domain'], $key);
            return $value === false ? null : $value ?? $key;
        }
 
        $value = self::lookup($state['domain'], $key);
        if ($value !== null) {
            return $value === false ? null : $value;
        }
 
        return self::lookup($state['domain'], ShippedTranslations::IDENTITY_CONTEXT . "\x04" . $key) === '1' ? $key : null;
    }

References $module, ILIAS\Language\ComponentTranslation\ShippedTranslations\IDENTITY_CONTEXT, ILIAS\Language\ComponentTranslation\TranslationGettextRepository\lookup(), and ILIAS\Language\ComponentTranslation\TranslationGettextRepository\servedState().

Here is the call graph for this function:

hasSymbolicLink()

static ILIAS\Language\ComponentTranslation\TranslationGettextRepository::hasSymbolicLink ( array  $paths )

staticprivate

Parameters

list<string>

$paths

Definition at line 294 of file TranslationGettextRepository.php.

                                                         : bool
    {
        foreach ($paths as $path) {
            if (is_link($path)) {
                return true;
            }
        }
 
        return false;
    }

invalidateAll()

ILIAS\Language\ComponentTranslation\TranslationGettextRepository::invalidateAll

(

)

Forgets everything read so far, see MigratedTranslations::reset().

Definition at line 137 of file TranslationGettextRepository.php.

                                   : void
    {
        self::$build_keys = [];
        self::$states = [];
    }

invalidateLanguage()

ILIAS\Language\ComponentTranslation\TranslationGettextRepository::invalidateLanguage

(

string

$lang_key

)

Forgets what was read for $lang_key (e.g.

it was uninstalled).

Definition at line 125 of file TranslationGettextRepository.php.

                                                        : void
    {
        foreach (array_keys(self::$states) as $cache_key) {
            if (str_ends_with((string) $cache_key, '|' . $lang_key)) {
                unset(self::$states[$cache_key]);
            }
        }
    }

invalidateModule()

ILIAS\Language\ComponentTranslation\TranslationGettextRepository::invalidateModule	(	string	$module,
		string	$lang_key
	)

Forgets what was read for $module/$lang_key, so a local change just written is served.

Definition at line 117 of file TranslationGettextRepository.php.

                                                                      : void
    {
        unset(self::$states[$module . '|' . $lang_key]);
    }

References $module.

lookup()

static ILIAS\Language\ComponentTranslation\TranslationGettextRepository::lookup ( string  $domain, string  $message_id  )

staticprivate

The translation of $message_id in.

$domain: null if native gettext answers with $message_id (none), false if it does not work any more (settings changed and it cannot be activated again); retried after activating it again.

Definition at line 269 of file TranslationGettextRepository.php.

                                                                      : string|false|null
    {
        $value = NativeGettext::translate($domain, $message_id);
        if ($value !== $message_id) {
            return $value;
        }
        if (!NativeGettext::isActive()) {
            if (!NativeGettext::reactivateIfLost()) {
                self::reportLostActivation();
                return false;
            }
            $value = NativeGettext::translate($domain, $message_id);
        }
 
        return $value === $message_id ? null : $value;
    }

References ILIAS\Language\ComponentTranslation\NativeGettext\isActive(), ILIAS\Language\ComponentTranslation\NativeGettext\reactivateIfLost(), ILIAS\Language\ComponentTranslation\TranslationGettextRepository\reportLostActivation(), and ILIAS\Language\ComponentTranslation\NativeGettext\translate().

Referenced by ILIAS\Language\ComponentTranslation\TranslationGettextRepository\getText().

Here is the call graph for this function:

Here is the caller graph for this function:

readStart()

static ILIAS\Language\ComponentTranslation\TranslationGettextRepository::readStart ( string  $file, int  $length  )

staticprivate

At most the first $length bytes of $file, null if it cannot be read.

Definition at line 308 of file TranslationGettextRepository.php.

                                                                : ?string
    {
        $handle = is_file($file) ? @fopen($file, 'rb') : false;
        if ($handle === false) {
            return null;
        }
        try {
            $content = fread($handle, $length);
            return $content === false ? null : $content;
        } finally {
            fclose($handle);
        }
    }

Referenced by ILIAS\Language\ComponentTranslation\TranslationGettextRepository\withOverlay().

Here is the caller graph for this function:

reportLostActivation()

static ILIAS\Language\ComponentTranslation\TranslationGettextRepository::reportLostActivation ( )

staticprivate

Definition at line 286 of file TranslationGettextRepository.php.

                                                  : void
    {
        MigratedTranslations::reportActivationProblem(NativeGettext::getProblem() ?? 'LC_MESSAGES or LANGUAGE were changed and it cannot be activated again');
    }

References ILIAS\Language\ComponentTranslation\NativeGettext\getProblem(), and ILIAS\Language\ComponentTranslation\MigratedTranslations\reportActivationProblem().

Referenced by ILIAS\Language\ComponentTranslation\TranslationGettextRepository\getPluralText(), and ILIAS\Language\ComponentTranslation\TranslationGettextRepository\lookup().

Here is the call graph for this function:

Here is the caller graph for this function:

servedState()

static ILIAS\Language\ComponentTranslation\TranslationGettextRepository::servedState ( string  $module, string  $lang_key, string  $key, ?string  $client_data_dir  )

staticprivate

The state of $module/$lang_key if it is readable and lists the identifier $key, null otherwise.

Returns

State|null

Definition at line 148 of file TranslationGettextRepository.php.

                                                                                                                : ?array
    {
        $state = self::state($module, $lang_key, $client_data_dir);
 
        return $state !== null && $state['ok'] && isset($state['keys'][$key]) ? $state : null;
    }

References $module, and ILIAS\Language\ComponentTranslation\TranslationGettextRepository\state().

Referenced by ILIAS\Language\ComponentTranslation\TranslationGettextRepository\getPluralText(), and ILIAS\Language\ComponentTranslation\TranslationGettextRepository\getText().

Here is the call graph for this function:

Here is the caller graph for this function:

state()

static ILIAS\Language\ComponentTranslation\TranslationGettextRepository::state ( string  $module, string  $lang_key, ?string  $client_data_dir  )

staticprivate

Returns

State|null

Definition at line 158 of file TranslationGettextRepository.php.

                                                                                             : ?array
    {
        $cache_key = $module . '|' . $lang_key;
        if (array_key_exists($cache_key, self::$states)) {
            $state = self::$states[$cache_key];
            // the client data directory became known later in the request (e.g. Setup)
            if ($state !== null && $state['ok'] && !$state['overlay_checked'] && $client_data_dir !== null) {
                $state = self::$states[$cache_key] = self::withOverlay($state, $client_data_dir, $module, $lang_key);
            }
            return $state;
        }
        $pointer = MigratedTranslations::pointer();
        if (
            $pointer === null
            || $pointer['build'] === null
            || !MigratedLanguageFilePaths::isValidModule($module)
            || !MigratedLanguageFilePaths::isValidLanguageKey($lang_key)
            || !in_array($lang_key, $pointer['modules'][$module] ?? [], true)
        ) {
            return self::$states[$cache_key] = null;
        }
 
        $build_directory = MigratedLanguageFilePaths::buildDirectory(MigratedTranslations::artifactDirectory(), $pointer['build']);
        $domain = MigratedLanguageFilePaths::shippedDomain($module, $lang_key);
        $keys = self::buildKeys($build_directory, $module);
        $state = ['keys' => $keys ?? [], 'ok' => false, 'domain' => $domain, 'overlay_domain' => null, 'overlay_keys' => [], 'overlay_checked' => false];
        if ($keys === null) {
            MigratedTranslations::reportProblem(sprintf(
                'The identifiers of module "%s" cannot be read from "%s" - run "php cli/setup.php build".',
                $module,
                MigratedLanguageFilePaths::buildKeysFile($build_directory, $module)
            ));
        } elseif (!NativeGettext::activate(MigratedLanguageFilePaths::buildLocaleDirectory($build_directory))) {
            MigratedTranslations::reportActivationProblem(
                (NativeGettext::isExtensionLoaded() ? ShippedTranslationsBuild::platformProblem($build_directory) : null)
                    ?? (string) NativeGettext::getProblem()
            );
        } elseif (!NativeGettext::bind($domain, $build_directory) || !NativeGettext::isLoaded($domain)) {
            MigratedTranslations::reportProblem(sprintf(
                'Native gettext cannot read "%s" - run "php cli/setup.php build".',
                MigratedLanguageFilePaths::buildMoFile($build_directory, $module, $lang_key)
            ), true);
        } else {
            $state['ok'] = true;
            if ($client_data_dir !== null) {
                $state = self::withOverlay($state, $client_data_dir, $module, $lang_key);
            }
        }
 
        return self::$states[$cache_key] = $state;
    }

References $module, ILIAS\Language\ComponentTranslation\NativeGettext\activate(), ILIAS\Language\ComponentTranslation\MigratedTranslations\artifactDirectory(), ILIAS\Language\ComponentTranslation\NativeGettext\bind(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\buildDirectory(), ILIAS\Language\ComponentTranslation\TranslationGettextRepository\buildKeys(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\buildKeysFile(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\buildLocaleDirectory(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\buildMoFile(), ILIAS\Language\ComponentTranslation\NativeGettext\getProblem(), ILIAS\Language\ComponentTranslation\NativeGettext\isExtensionLoaded(), ILIAS\Language\ComponentTranslation\NativeGettext\isLoaded(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\isValidLanguageKey(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\isValidModule(), ILIAS\Language\ComponentTranslation\ShippedTranslationsBuild\platformProblem(), ILIAS\Language\ComponentTranslation\MigratedTranslations\pointer(), ILIAS\Language\ComponentTranslation\MigratedTranslations\reportActivationProblem(), ILIAS\Language\ComponentTranslation\MigratedTranslations\reportProblem(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\shippedDomain(), and ILIAS\Language\ComponentTranslation\TranslationGettextRepository\withOverlay().

Referenced by ILIAS\Language\ComponentTranslation\TranslationGettextRepository\getKeys(), and ILIAS\Language\ComponentTranslation\TranslationGettextRepository\servedState().

Here is the call graph for this function:

Here is the caller graph for this function:

withOverlay()

static ILIAS\Language\ComponentTranslation\TranslationGettextRepository::withOverlay ( array  $state, string  $client_data_dir, string  $module, string  $lang_key  )

staticprivate

$state with the overlay revision current of the overlay of $module/$lang_key names, if any.

Parameters

State

$state

Returns

State

Definition at line 216 of file TranslationGettextRepository.php.

                                                                                                                : array
    {
        $state['overlay_checked'] = true;
        $overlay_directory = MigratedLanguageFilePaths::overlayDirectory($client_data_dir, $module, $lang_key);
        $current_file = MigratedLanguageFilePaths::overlayCurrentFile($overlay_directory);
        if (!file_exists($current_file) && !is_link($current_file)) {
            return $state;
        }
        // like the write path: no symbolic link below the overlay root is followed
        if (self::hasSymbolicLink([dirname($overlay_directory), $overlay_directory, $current_file])) {
            MigratedTranslations::reportProblem(sprintf('The overlay "%s" contains a symbolic link - its local changes are not served.', $overlay_directory));
            return $state;
        }
        $revision = self::readStart($current_file, self::MAX_REVISION_FILE_SIZE);
        $revision = $revision === null ? '' : trim($revision);
        if (!MigratedLanguageFilePaths::isOverlayRevision($revision)) {
            MigratedTranslations::reportProblem(sprintf('The overlay "%s" names no valid revision - its local changes are not served.', $current_file));
            return $state;
        }
        $revision_directory = MigratedLanguageFilePaths::overlayRevisionDirectory($overlay_directory, $revision);
        $keys_file = MigratedLanguageFilePaths::overlayKeysFile($revision_directory);
        $mo_file = MigratedLanguageFilePaths::overlayMoFile($revision_directory, $module, $lang_key);
        if (self::hasSymbolicLink([$revision_directory, dirname($mo_file, 2), dirname($mo_file), $mo_file, $keys_file])) {
            MigratedTranslations::reportProblem(sprintf('The overlay revision "%s" contains a symbolic link - its local changes are not served.', $revision_directory));
            return $state;
        }
        $content = @file_get_contents($keys_file);
        $keys = $content === false ? null : json_decode($content, true);
        if (!is_array($keys) || !array_is_list($keys) || array_filter($keys, 'is_string') !== $keys) {
            MigratedTranslations::reportProblem(sprintf('The overlay revision "%s" has no valid "keys.json" - its local changes are not served.', $revision_directory));
            return $state;
        }
        $domain = MigratedLanguageFilePaths::overlayDomain($module, $lang_key);
        if (!NativeGettext::bind($domain, $revision_directory) || !NativeGettext::isLoaded($domain)) {
            MigratedTranslations::reportProblem(sprintf(
                'Native gettext cannot read "%s" - its local changes are not served.',
                MigratedLanguageFilePaths::overlayMoFile($revision_directory, $module, $lang_key)
            ));
            return $state;
        }
 
        $state['overlay_domain'] = $domain;
        $state['overlay_keys'] = array_fill_keys($keys, true);
        $state['keys'] += array_fill_keys($keys, $module);
 
        return $state;
    }

References $module, ILIAS\Language\ComponentTranslation\NativeGettext\bind(), ILIAS\Language\ComponentTranslation\NativeGettext\isLoaded(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\isOverlayRevision(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\overlayCurrentFile(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\overlayDirectory(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\overlayDomain(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\overlayKeysFile(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\overlayMoFile(), ILIAS\Language\ComponentTranslation\MigratedLanguageFilePaths\overlayRevisionDirectory(), ILIAS\Language\ComponentTranslation\TranslationGettextRepository\readStart(), and ILIAS\Language\ComponentTranslation\MigratedTranslations\reportProblem().

Referenced by ILIAS\Language\ComponentTranslation\TranslationGettextRepository\state().

Here is the call graph for this function:

Here is the caller graph for this function:

Field Documentation

$build_keys

array ILIAS\Language\ComponentTranslation\TranslationGettextRepository::$build_keys = []

staticprivate

Definition at line 50 of file TranslationGettextRepository.php.

$states

array ILIAS\Language\ComponentTranslation\TranslationGettextRepository::$states = []

staticprivate

Definition at line 57 of file TranslationGettextRepository.php.

MAX_REVISION_FILE_SIZE

const int ILIAS\Language\ComponentTranslation\TranslationGettextRepository::MAX_REVISION_FILE_SIZE = 128

private

current only holds the name of a revision - more is never read.

Definition at line 62 of file TranslationGettextRepository.php.

---

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

• components/ILIAS/Language/src/ComponentTranslation/TranslationGettextRepository.php