TYPO3 12.4 API: LanguageService

LanguageService

Main API to fetch labels from XLF (label files) based on the current system language of TYPO3. It is able to resolve references to files + their pointers to the proper language. If you see something about "LLL", this class does the trick for you. It is not related to language handling of content, but rather of labels for plugins.

Usually this is injected into $GLOBALS['LANG'] when in backend or CLI context, and populated by the current backend user. Do not rely on $GLOBAL['LANG'] in frontend, as it is only available under certain circumstances! In frontend, this is also used to translate "labels", see TypoScriptFrontendController->sL() for that.

As TYPO3 internally does not match the proper ISO locale standard, the "locale" here is actually a list of supported language keys, (see Locales class), whereas "English" has the language key "default".

Further usages on setting up your own LanguageService in BE:

$languageService = GeneralUtility::makeInstance(LanguageServiceFactory::class)
    ->createFromUserPreferences($GLOBALS['BE_USER']);

Properties

$debugKey : bool: If true, will show the key/location of labels in the backend.
$lang : string: This is set to the language that is currently running for the user
$labels : array<string|int, array<string|int, string>>
$locale : Locale|null
$locales : Locales
$localizationFactory : LocalizationFactory
$overrideLabels : array<string|int, array<string|int, string>>
$runtimeCache : FrontendInterface

Methods

__construct() : mixed
getLabelsFromResource() : array<string, string>: Load all labels from a resource/file and returns them in a translated fashion.
getLL() : string: Returns the label with key $index from the globally loaded $LOCAL_LANG array.
getLocale() : Locale|null
includeLLFile() : array<string|int, mixed>: Includes locallang file (and possibly additional localized version, if configured for) Read language labels will be merged with $LOCAL_LANG.
init() : void: Initializes the language to fetch XLF labels for.
overrideLabels() : void: Define custom labels which can be overridden for a given file. This is typically the case for TypoScript plugins.
sL() : string: Main and most often used method.
translateLabel() : string: Translates prepared labels which are handed in, and also uses the fallback if no language is given.
debugLL() : string: Debugs the localization key.
getLLL() : string: Returns the label with key $index from the $LOCAL_LANG array used as the second argument
readLLfile() : array<string|int, mixed>: Includes a locallang file and returns the $LOCAL_LANG array found inside.

$debugKey

If true, will show the key/location of labels in the backend.

Deprecated

since TYPO3 v12.4. will be removed in TYPO3 v13.0.


    public
        bool
    $debugKey
     = false

$lang

This is set to the language that is currently running for the user


    public
        string
    $lang
     = 'default'

$labels


    protected
        array<string|int, array<string|int, string>>
    $labels
     = []

$locale


    protected
        Locale|null
    $locale
     = null

$locales


    protected
        Locales
    $locales

$localizationFactory


    protected
        LocalizationFactory
    $localizationFactory

$overrideLabels


    protected
        array<string|int, array<string|int, string>>
    $overrideLabels
     = []

$runtimeCache


    protected
        FrontendInterface
    $runtimeCache

__construct()


    public
                    __construct(Locales $locales, LocalizationFactory $localizationFactory, FrontendInterface $runtimeCache) : mixed

Parameters

$locales : Locales
$localizationFactory : LocalizationFactory
$runtimeCache : FrontendInterface

Internal

use LanguageServiceFactory instead

getLabelsFromResource()

Load all labels from a resource/file and returns them in a translated fashion.


    public
                    getLabelsFromResource(string $fileRef) : array<string, string>

Parameters

$fileRef : string

Internal

not part of TYPO3 Core API for the time being.

Return values

array<string, string>

getLL()

Returns the label with key $index from the globally loaded $LOCAL_LANG array.


    public
                    getLL(string $index) : string

Deprecated

will be removed in TYPO3 v13.0. Use sL() instead.

Mostly used from modules with only one LOCAL_LANG file loaded into the global space.

Parameters

$index : string: Label key

Return values

string

getLocale()


    public
                    getLocale() : Locale|null

Return values

Locale|null

includeLLFile()

Includes locallang file (and possibly additional localized version, if configured for) Read language labels will be merged with $LOCAL_LANG.


    public
                    includeLLFile(string $fileRef) : array<string|int, mixed>

Parameters

$fileRef : string: $fileRef is a file-reference

Internal

do not rely on this method as it is only used for internal purposes in TYPO3 v13.0.

Return values

array<string|int, mixed> —

returns the loaded label file

init()

Initializes the language to fetch XLF labels for.


    public
                    init(Locale|string $languageKey) : void

$languageService = GeneralUtility::makeInstance(LanguageServiceFactory::class)
    ->createFromUserPreferences($GLOBALS['BE_USER']);

Parameters

$languageKey : Locale|string: The language key (two character string from backend users profile)

Internal

use one of the factory methods instead

overrideLabels()

Define custom labels which can be overridden for a given file. This is typically the case for TypoScript plugins.


    public
                    overrideLabels(string $fileRef, array<string|int, mixed> $labels) : void

Parameters

$fileRef : string
$labels : array<string|int, mixed>

sL()

Main and most often used method.


    public
                    sL(string $input) : string

Resolve strings like these:

'LLL:EXT:core/Resources/Private/Language/locallang_core.xlf:labels.depth_0'

This looks up the given .xlf file path in the 'core' extension for label labels.depth_0

Only the plain string contents of a language key, like "Record title: %s" are returned. Placeholder interpolation must be performed separately, for example via sprintf(), like LocalizationUtility::translate() does internally (which should only be used in Extbase context)

Example: Label is defined in EXT:my_ext/Resources/Private/Language/locallang.xlf as:

<trans-unit id="downloaded_times">
    <source>downloaded %d times from %s locations</source>
</trans-unit>

The following code example assumes $this->request to hold the current request object. There are several ways to create the LanguageService using the Factory, depending on the context. Please adjust this example to your use case:

$language = $this->request->getAttribute('language');
$languageService =
  GeneralUtility::makeInstance(LanguageServiceFactory::class)
  ->createFromSiteLanguage($language);
$label = sprintf(
     $languageService->sL(
         'LLL:EXT:my_ext/Resources/Private/Language/locallang.xlf:downloaded_times'
     ),
     27,
     'several'
);

This will result in $label to contain 'downloaded 27 times from several locations'.

Parameters

$input : string: Label key/reference

Return values

string

translateLabel()

Translates prepared labels which are handed in, and also uses the fallback if no language is given.


    public
                    translateLabel(array<string|int, mixed>|string $input, string $fallback) : string

This is common in situations such as page TSconfig where labels or references to labels are used.

Parameters

$input : array<string|int, mixed>|string
$fallback : string

Internal

not part of TYPO3 Core API for the time being.

Return values

string

debugLL()

Debugs the localization key.


    protected
                    debugLL(string $labelIdentifier) : string

Deprecated

since TYPO3 v12.4. will be removed in TYPO3 v13.0.

Parameters

$labelIdentifier : string: to be shown next to the value

Return values

string

getLLL()

Returns the label with key $index from the $LOCAL_LANG array used as the second argument


    protected
                    getLLL(string $index, array<string|int, mixed> $localLanguage) : string

Parameters

$index : string: Label key
$localLanguage : array<string|int, mixed>: $LOCAL_LANG array to get label key from

Return values

string

readLLfile()

Includes a locallang file and returns the $LOCAL_LANG array found inside.


    protected
                    readLLfile(string $fileRef) : array<string|int, mixed>

Parameters

$fileRef : string: Input is a file-reference to be a 'local_lang' file containing a $LOCAL_LANG array

Return values

array<string|int, mixed> —

value of $LOCAL_LANG found in the included file, empty if none found

LanguageService

Table of Contents

Properties

Methods

Properties

$debugKey

$lang

$labels

$locale

$locales

$localizationFactory

$overrideLabels

$runtimeCache

Methods

__construct()

Parameters

getLabelsFromResource()

Parameters

Return values

getLL()

Parameters

Return values

getLocale()

Return values

includeLLFile()

Parameters

Return values

init()

Parameters

Tags

overrideLabels()

Parameters

sL()

Parameters

Tags

Return values

translateLabel()

Parameters

Return values

debugLL()

Parameters

Return values

getLLL()

Parameters

Return values

readLLfile()

Parameters

Return values