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