13d5b9e00df8fc0bcc7ca96ce5df4a1946236a44
[Packages/TYPO3.CMS.git] / typo3 / sysext / extbase / Classes / Utility / LocalizationUtility.php
1 <?php
2 declare(strict_types = 1);
3
4 namespace TYPO3\CMS\Extbase\Utility;
5
6 /*
7 * This file is part of the TYPO3 CMS project.
8 *
9 * It is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, either version 2
11 * of the License, or any later version.
12 *
13 * For the full copyright and license information, please read the
14 * LICENSE.txt file that was distributed with this source code.
15 *
16 * The TYPO3 project - inspiring people to share!
17 */
18
19 use Psr\Http\Message\ServerRequestInterface;
20 use TYPO3\CMS\Core\Localization\Locales;
21 use TYPO3\CMS\Core\Localization\LocalizationFactory;
22 use TYPO3\CMS\Core\Site\Entity\SiteLanguage;
23 use TYPO3\CMS\Core\Utility\GeneralUtility;
24 use TYPO3\CMS\Extbase\Configuration\ConfigurationManagerInterface;
25 use TYPO3\CMS\Extbase\Object\ObjectManager;
26
27 /**
28 * Localization helper which should be used to fetch localized labels.
29 */
30 class LocalizationUtility
31 {
32 /**
33 * @var string
34 */
35 protected static $locallangPath = 'Resources/Private/Language/';
36
37 /**
38 * Local Language content
39 *
40 * @var array
41 */
42 protected static $LOCAL_LANG = [];
43
44 /**
45 * Contains those LL keys, which have been set to (empty) in TypoScript.
46 * This is necessary, as we cannot distinguish between a nonexisting
47 * translation and a label that has been cleared by TS.
48 * In both cases ['key'][0]['target'] is "".
49 *
50 * @var array
51 */
52 protected static $LOCAL_LANG_UNSET = [];
53
54 /**
55 * @var \TYPO3\CMS\Extbase\Configuration\ConfigurationManagerInterface
56 */
57 protected static $configurationManager;
58
59 /**
60 * Returns the localized label of the LOCAL_LANG key, $key.
61 *
62 * @param string $key The key from the LOCAL_LANG array for which to return the value.
63 * @param string|null $extensionName The name of the extension
64 * @param array $arguments The arguments of the extension, being passed over to vsprintf
65 * @param string $languageKey The language key or null for using the current language from the system
66 * @param string[] $alternativeLanguageKeys The alternative language keys if no translation was found. If null and we are in the frontend, then the language_alt from TypoScript setup will be used
67 * @return string|null The value from LOCAL_LANG or null if no translation was found.
68 */
69 public static function translate(string $key, ?string $extensionName = null, array $arguments = null, string $languageKey = null, array $alternativeLanguageKeys = null): ?string
70 {
71 if ($key === '') {
72 // Early return guard: returns null if the key was empty, because the key may be a dynamic value
73 // (from for example Fluid). Returning null allows null coalescing to a default value when that happens.
74 return null;
75 }
76 $value = null;
77 if (GeneralUtility::isFirstPartOfStr($key, 'LLL:')) {
78 $keyParts = explode(':', $key);
79 unset($keyParts[0]);
80 $key = array_pop($keyParts);
81 $languageFilePath = implode(':', $keyParts);
82 } else {
83 if (empty($extensionName)) {
84 throw new \InvalidArgumentException(
85 'Parameter $extensionName cannot be empty if a fully-qualified key is not specified.',
86 1498144052
87 );
88 }
89 $languageFilePath = static::getLanguageFilePath($extensionName);
90 }
91 $languageKeys = static::getLanguageKeys();
92 if ($languageKey === null) {
93 $languageKey = $languageKeys['languageKey'];
94 }
95 if (empty($alternativeLanguageKeys)) {
96 $alternativeLanguageKeys = $languageKeys['alternativeLanguageKeys'];
97 }
98 static::initializeLocalization($languageFilePath, $languageKey, $alternativeLanguageKeys, $extensionName);
99
100 // The "from" charset of csConv() is only set for strings from TypoScript via _LOCAL_LANG
101 if (!empty(self::$LOCAL_LANG[$languageFilePath][$languageKey][$key][0]['target'])
102 || isset(self::$LOCAL_LANG_UNSET[$languageFilePath][$languageKey][$key])
103 ) {
104 // Local language translation for key exists
105 $value = self::$LOCAL_LANG[$languageFilePath][$languageKey][$key][0]['target'];
106 } elseif (!empty($alternativeLanguageKeys)) {
107 $languages = array_reverse($alternativeLanguageKeys);
108 foreach ($languages as $language) {
109 if (!empty(self::$LOCAL_LANG[$languageFilePath][$language][$key][0]['target'])
110 || isset(self::$LOCAL_LANG_UNSET[$languageFilePath][$language][$key])
111 ) {
112 // Alternative language translation for key exists
113 $value = self::$LOCAL_LANG[$languageFilePath][$language][$key][0]['target'];
114 break;
115 }
116 }
117 }
118 if ($value === null && (!empty(self::$LOCAL_LANG[$languageFilePath]['default'][$key][0]['target'])
119 || isset(self::$LOCAL_LANG_UNSET[$languageFilePath]['default'][$key]))
120 ) {
121 // Default language translation for key exists
122 // No charset conversion because default is English and thereby ASCII
123 $value = self::$LOCAL_LANG[$languageFilePath]['default'][$key][0]['target'];
124 }
125
126 if (is_array($arguments) && $value !== null) {
127 // This unrolls arguments from $arguments - instead of calling vsprintf which receives arguments as an array.
128 // The reason is that only sprintf() will return an error message if the number of arguments does not match
129 // the number of placeholders in the format string. Whereas, vsprintf would silently return nothing.
130 return sprintf($value, ...array_values($arguments)) ?: sprintf('Error: could not translate key "%s" with value "%s" and %d argument(s)!', $key, $value, count($arguments));
131 }
132 return $value;
133 }
134
135 /**
136 * Loads local-language values by looking for a "locallang.xlf" (or "locallang.xml") file in the plugin resources directory and if found includes it.
137 * Also locallang values set in the TypoScript property "_LOCAL_LANG" are merged onto the values found in the "locallang.xlf" file.
138 *
139 * @param string $languageFilePath
140 * @param string $languageKey
141 * @param string[] $alternativeLanguageKeys
142 * @param string $extensionName
143 */
144 protected static function initializeLocalization(string $languageFilePath, string $languageKey, array $alternativeLanguageKeys, string $extensionName = null): void
145 {
146 $languageFactory = GeneralUtility::makeInstance(LocalizationFactory::class);
147
148 if (empty(self::$LOCAL_LANG[$languageFilePath][$languageKey])) {
149 $parsedData = $languageFactory->getParsedData($languageFilePath, $languageKey);
150 foreach ($parsedData as $tempLanguageKey => $data) {
151 if (!empty($data)) {
152 self::$LOCAL_LANG[$languageFilePath][$tempLanguageKey] = $data;
153 }
154 }
155 }
156 if ($languageKey !== 'default') {
157 foreach ($alternativeLanguageKeys as $alternativeLanguageKey) {
158 if (empty(self::$LOCAL_LANG[$languageFilePath][$alternativeLanguageKey])) {
159 $tempLL = $languageFactory->getParsedData($languageFilePath, $alternativeLanguageKey);
160 if (isset($tempLL[$alternativeLanguageKey])) {
161 self::$LOCAL_LANG[$languageFilePath][$alternativeLanguageKey] = $tempLL[$alternativeLanguageKey];
162 }
163 }
164 }
165 }
166 if (!empty($extensionName)) {
167 static::loadTypoScriptLabels($extensionName, $languageFilePath);
168 }
169 }
170
171 /**
172 * Returns the default path and filename for an extension
173 *
174 * @param string $extensionName
175 * @return string
176 */
177 protected static function getLanguageFilePath(string $extensionName): string
178 {
179 return 'EXT:' . GeneralUtility::camelCaseToLowerCaseUnderscored($extensionName) . '/' . self::$locallangPath . 'locallang.xlf';
180 }
181
182 /**
183 * Sets the currently active language/language_alt keys.
184 * Default values are "default" for language key and an empty array for language_alt key.
185 *
186 * @return array
187 */
188 protected static function getLanguageKeys(): array
189 {
190 $languageKeys = [
191 'languageKey' => 'default',
192 'alternativeLanguageKeys' => [],
193 ];
194 if (TYPO3_MODE === 'FE') {
195 $tsfe = static::getTypoScriptFrontendController();
196 $siteLanguage = self::getCurrentSiteLanguage();
197
198 // Get values from site language, which takes precedence over TypoScript settings
199 if ($siteLanguage instanceof SiteLanguage) {
200 $languageKeys['languageKey'] = $siteLanguage->getTypo3Language();
201 } elseif (isset($tsfe->config['config']['language'])) {
202 $languageKeys['languageKey'] = $tsfe->config['config']['language'];
203 if (isset($tsfe->config['config']['language_alt'])) {
204 $languageKeys['alternativeLanguageKeys'] = $tsfe->config['config']['language_alt'];
205 }
206 }
207
208 if (empty($languageKeys['alternativeLanguageKeys'])) {
209 $locales = GeneralUtility::makeInstance(Locales::class);
210 if (in_array($languageKeys['languageKey'], $locales->getLocales())) {
211 foreach ($locales->getLocaleDependencies($languageKeys['languageKey']) as $language) {
212 $languageKeys['alternativeLanguageKeys'] = $language;
213 }
214 }
215 }
216 } elseif (!empty($GLOBALS['BE_USER']->uc['lang'])) {
217 $languageKeys['languageKey'] = $GLOBALS['BE_USER']->uc['lang'];
218 } elseif (!empty(static::getLanguageService()->lang)) {
219 $languageKeys['languageKey'] = static::getLanguageService()->lang;
220 }
221 return $languageKeys;
222 }
223
224 /**
225 * Overwrites labels that are set via TypoScript.
226 * TS locallang labels have to be configured like:
227 * plugin.tx_myextension._LOCAL_LANG.languageKey.key = value
228 *
229 * @param string $extensionName
230 * @param string $languageFilePath
231 */
232 protected static function loadTypoScriptLabels(string $extensionName, string $languageFilePath): void
233 {
234 $configurationManager = static::getConfigurationManager();
235 $frameworkConfiguration = $configurationManager->getConfiguration(ConfigurationManagerInterface::CONFIGURATION_TYPE_FRAMEWORK, $extensionName);
236 if (!is_array($frameworkConfiguration['_LOCAL_LANG'] ?? false)) {
237 return;
238 }
239 self::$LOCAL_LANG_UNSET[$languageFilePath] = [];
240 foreach ($frameworkConfiguration['_LOCAL_LANG'] as $languageKey => $labels) {
241 if (!is_array($labels)) {
242 continue;
243 }
244 foreach ($labels as $labelKey => $labelValue) {
245 if (is_string($labelValue)) {
246 self::$LOCAL_LANG[$languageFilePath][$languageKey][$labelKey][0]['target'] = $labelValue;
247 if ($labelValue === '') {
248 self::$LOCAL_LANG_UNSET[$languageFilePath][$languageKey][$labelKey] = '';
249 }
250 } elseif (is_array($labelValue)) {
251 $labelValue = self::flattenTypoScriptLabelArray($labelValue, $labelKey);
252 foreach ($labelValue as $key => $value) {
253 self::$LOCAL_LANG[$languageFilePath][$languageKey][$key][0]['target'] = $value;
254 if ($value === '') {
255 self::$LOCAL_LANG_UNSET[$languageFilePath][$languageKey][$key] = '';
256 }
257 }
258 }
259 }
260 }
261 }
262
263 /**
264 * Flatten TypoScript label array; converting a hierarchical array into a flat
265 * array with the keys separated by dots.
266 *
267 * Example Input: array('k1' => array('subkey1' => 'val1'))
268 * Example Output: array('k1.subkey1' => 'val1')
269 *
270 * @param array $labelValues Hierarchical array of labels
271 * @param string $parentKey the name of the parent key in the recursion; is only needed for recursion.
272 * @return array flattened array of labels.
273 */
274 protected static function flattenTypoScriptLabelArray(array $labelValues, string $parentKey = ''): array
275 {
276 $result = [];
277 foreach ($labelValues as $key => $labelValue) {
278 if (!empty($parentKey)) {
279 if ($key === '_typoScriptNodeValue') {
280 $key = $parentKey;
281 } else {
282 $key = $parentKey . '.' . $key;
283 }
284 }
285 if (is_array($labelValue)) {
286 $labelValue = self::flattenTypoScriptLabelArray($labelValue, $key);
287 $result = array_merge($result, $labelValue);
288 } else {
289 $result[$key] = $labelValue;
290 }
291 }
292 return $result;
293 }
294
295 /**
296 * Returns instance of the configuration manager
297 *
298 * @return \TYPO3\CMS\Extbase\Configuration\ConfigurationManagerInterface
299 */
300 protected static function getConfigurationManager(): ConfigurationManagerInterface
301 {
302 if (static::$configurationManager !== null) {
303 return static::$configurationManager;
304 }
305 $objectManager = GeneralUtility::makeInstance(ObjectManager::class);
306 $configurationManager = $objectManager->get(ConfigurationManagerInterface::class);
307 static::$configurationManager = $configurationManager;
308 return $configurationManager;
309 }
310
311 /**
312 * Returns the currently configured "site language" if a site is configured (= resolved)
313 * in the current request.
314 *
315 * @return SiteLanguage|null
316 */
317 protected static function getCurrentSiteLanguage(): ?SiteLanguage
318 {
319 if ($GLOBALS['TYPO3_REQUEST'] instanceof ServerRequestInterface) {
320 return $GLOBALS['TYPO3_REQUEST']->getAttribute('language', null);
321 }
322 return null;
323 }
324
325 /**
326 * @return \TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController
327 */
328 protected static function getTypoScriptFrontendController(): \TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController
329 {
330 return $GLOBALS['TSFE'];
331 }
332
333 /**
334 * @return \TYPO3\CMS\Core\Localization\LanguageService
335 */
336 protected static function getLanguageService(): \TYPO3\CMS\Core\Localization\LanguageService
337 {
338 return $GLOBALS['LANG'];
339 }
340 }