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!

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" is always the fallback ("default language").

Further usages on setting up your own LanguageService in BE:

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

Table of Contents

Properties

$lang  : string
This is set to the language which is currently running for the user
$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.
getLocale()  : Locale|null
init()  : void
Initializes the language to fetch XLF labels for.
loadTypoScriptLabelsFromExtension()  : array<string|int, mixed>
Overwrites labels that are set via TypoScript.
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.
translate()  : string|null
This is different from sL() as it can also return null, and expects a domain (can be a file reference as well), NULL is returned then the "id" is wrong.
translateLabel()  : string
Translates prepared labels which are handed in, and also uses the fallback if no language is given.
getLLL()  : string|null
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 labels found inside.

Properties

$lang

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

public string $lang = 'en'

$overrideLabels

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

Methods

getLabelsFromResource()

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

public getLabelsFromResource(string $fileReferenceOrDomain) : array<string, string>
Parameters
$fileReferenceOrDomain : string
Internal

not part of TYPO3 Core API for the time being.

Return values
array<string, string>

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

Tags
throws
RuntimeException

loadTypoScriptLabelsFromExtension()

Overwrites labels that are set via TypoScript.

public loadTypoScriptLabelsFromExtension(string $extensionName, FrontendTypoScript $typoScript[, string $pluginName = '' ]) : array<string|int, mixed>

TS labels have to be configured like: plugin.tx_myextension._LOCAL_LANG.languageKey.key = value

Parameters
$extensionName : string
$typoScript : FrontendTypoScript
$pluginName : string = ''
Internal

not part of TYPO3 Core API.

Return values
array<string|int, mixed>

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'
'LLL:core.messages:labels.depth_0'
'core.messages:labels.depth_0'  // LLL: prefix is optional

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

The LLL: prefix is optional. If the input contains a colon (:), it will be treated as a label reference. If no colon is found, the input string is returned as-is (constant non-localizable label).

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

Tags
see
LocalizationUtility::translate()
Return values
string

translate()

This is different from sL() as it can also return null, and expects a domain (can be a file reference as well), NULL is returned then the "id" is wrong.

public translate(string $id, string $domain[, array<string|int, mixed> $arguments = [] ]) : string|null
Parameters
$id : string
$domain : string
$arguments : array<string|int, mixed> = []
Internal

for the time being, there might be $locale added a later point, as well as $quantity and $defaultValue

Return values
string|null

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

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[, bool $returnNullIfNotSet = false ]) : string|null
Parameters
$index : string

Label key

$localLanguage : array<string|int, mixed>

$LOCAL_LANG array to get label key from

$returnNullIfNotSet : bool = false
Return values
string|null

readLLfile()

Includes a locallang file and returns the labels found inside.

protected readLLfile(string $fileReferenceOrDomain) : array<string|int, mixed>
Parameters
$fileReferenceOrDomain : 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


        

        
    




    

    

                            

            

                            
    

        On this page

        
    


            

                    

        

    

        

            
Search results