0b9065184b401aaaddaa9e6f601f4bf5d90c3fc2
[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 TYPO3\CMS\Core\Localization\Locales;
18 use TYPO3\CMS\Core\Localization\LocalizationFactory;
19 use TYPO3\CMS\Core\Utility\GeneralUtility;
20 use TYPO3\CMS\Extbase\Configuration\ConfigurationManagerInterface;
21 use TYPO3\CMS\Extbase\Object\ObjectManager;
22
23 /**
24 * Localization helper which should be used to fetch localized labels.
25 *
26 * @api
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 * Key of the language to use
54 *
55 * @var string
56 */
57 protected static $languageKey = 'default';
58
59 /**
60 * Pointer to alternative fall-back language to use
61 *
62 * @var array
63 */
64 protected static $alternativeLanguageKeys = [];
65
66 /**
67 * @var \TYPO3\CMS\Extbase\Configuration\ConfigurationManagerInterface
68 */
69 protected static $configurationManager = null;
70
71 /**
72 * Returns the localized label of the LOCAL_LANG key, $key.
73 *
74 * @param string $key The key from the LOCAL_LANG array for which to return the value.
75 * @param string|null $extensionName The name of the extension
76 * @param array $arguments the arguments of the extension, being passed over to vsprintf
77 * @return string|NULL The value from LOCAL_LANG or NULL if no translation was found.
78 * @api
79 * @todo : If vsprintf gets a malformed string, it returns FALSE! Should we throw an exception there?
80 */
81 public static function translate($key, $extensionName = null, $arguments = null)
82 {
83 $value = null;
84 if (GeneralUtility::isFirstPartOfStr($key, 'LLL:')) {
85 $value = self::translateFileReference($key);
86 } else {
87 if (empty($extensionName)) {
88 throw new \InvalidArgumentException(
89 'Parameter $extensionName cannot be empty if a fully-qualified key is not specified.',
90 1498144052
91 );
92 }
93 self::initializeLocalization($extensionName);
94 // The "from" charset of csConv() is only set for strings from TypoScript via _LOCAL_LANG
95 if (!empty(self::$LOCAL_LANG[$extensionName][self::$languageKey][$key][0]['target'])
96 || isset(self::$LOCAL_LANG_UNSET[$extensionName][self::$languageKey][$key])
97 ) {
98 // Local language translation for key exists
99 $value = self::$LOCAL_LANG[$extensionName][self::$languageKey][$key][0]['target'];
100 } elseif (!empty(self::$alternativeLanguageKeys)) {
101 $languages = array_reverse(self::$alternativeLanguageKeys);
102 foreach ($languages as $language) {
103 if (!empty(self::$LOCAL_LANG[$extensionName][$language][$key][0]['target'])
104 || isset(self::$LOCAL_LANG_UNSET[$extensionName][$language][$key])
105 ) {
106 // Alternative language translation for key exists
107 $value = self::$LOCAL_LANG[$extensionName][$language][$key][0]['target'];
108 break;
109 }
110 }
111 }
112 if ($value === null && (!empty(self::$LOCAL_LANG[$extensionName]['default'][$key][0]['target'])
113 || isset(self::$LOCAL_LANG_UNSET[$extensionName]['default'][$key]))
114 ) {
115 // Default language translation for key exists
116 // No charset conversion because default is English and thereby ASCII
117 $value = self::$LOCAL_LANG[$extensionName]['default'][$key][0]['target'];
118 }
119 }
120 if (is_array($arguments) && $value !== null) {
121 return vsprintf($value, $arguments);
122 }
123 return $value;
124 }
125
126 /**
127 * Returns the localized label of the LOCAL_LANG key, $key.
128 *
129 * @param string $key The language key including the path to a custom locallang file ("LLL:path:key").
130 * @return string The value from LOCAL_LANG or NULL if no translation was found.
131 * @see language::sL()
132 * @see \TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController::sL()
133 */
134 protected static function translateFileReference($key)
135 {
136 if (TYPO3_MODE === 'FE') {
137 $value = self::getTypoScriptFrontendController()->sL($key);
138 return $value !== false ? $value : null;
139 }
140 if (is_object($GLOBALS['LANG'])) {
141 $value = self::getLanguageService()->sL($key);
142 return $value !== '' ? $value : null;
143 }
144 return $key;
145 }
146
147 /**
148 * Loads local-language values by looking for a "locallang.xlf" (or "locallang.xml") file in the plugin resources directory and if found includes it.
149 * Also locallang values set in the TypoScript property "_LOCAL_LANG" are merged onto the values found in the "locallang.xlf" file.
150 *
151 * @param string $extensionName
152 */
153 protected static function initializeLocalization($extensionName)
154 {
155 if (isset(self::$LOCAL_LANG[$extensionName])) {
156 return;
157 }
158 $locallangPathAndFilename = 'EXT:' . GeneralUtility::camelCaseToLowerCaseUnderscored($extensionName) . '/' . self::$locallangPath . 'locallang.xlf';
159 self::setLanguageKeys();
160
161 /** @var $languageFactory LocalizationFactory */
162 $languageFactory = GeneralUtility::makeInstance(LocalizationFactory::class);
163
164 self::$LOCAL_LANG[$extensionName] = $languageFactory->getParsedData($locallangPathAndFilename, self::$languageKey, 'utf-8');
165 foreach (self::$alternativeLanguageKeys as $language) {
166 $tempLL = $languageFactory->getParsedData($locallangPathAndFilename, $language, 'utf-8');
167 if (self::$languageKey !== 'default' && isset($tempLL[$language])) {
168 self::$LOCAL_LANG[$extensionName][$language] = $tempLL[$language];
169 }
170 }
171 self::loadTypoScriptLabels($extensionName);
172 }
173
174 /**
175 * Sets the currently active language/language_alt keys.
176 * Default values are "default" for language key and "" for language_alt key.
177 */
178 protected static function setLanguageKeys()
179 {
180 self::$languageKey = 'default';
181 self::$alternativeLanguageKeys = [];
182 if (TYPO3_MODE === 'FE') {
183 if (isset(self::getTypoScriptFrontendController()->config['config']['language'])) {
184 self::$languageKey = self::getTypoScriptFrontendController()->config['config']['language'];
185 if (isset(self::getTypoScriptFrontendController()->config['config']['language_alt'])) {
186 self::$alternativeLanguageKeys[] = self::getTypoScriptFrontendController()->config['config']['language_alt'];
187 } else {
188 /** @var $locales \TYPO3\CMS\Core\Localization\Locales */
189 $locales = GeneralUtility::makeInstance(Locales::class);
190 if (in_array(self::$languageKey, $locales->getLocales())) {
191 foreach ($locales->getLocaleDependencies(self::$languageKey) as $language) {
192 self::$alternativeLanguageKeys[] = $language;
193 }
194 }
195 }
196 }
197 } elseif (!empty($GLOBALS['BE_USER']->uc['lang'])) {
198 self::$languageKey = $GLOBALS['BE_USER']->uc['lang'];
199 } elseif (!empty(self::getLanguageService()->lang)) {
200 self::$languageKey = self::getLanguageService()->lang;
201 }
202 }
203
204 /**
205 * Overwrites labels that are set via TypoScript.
206 * TS locallang labels have to be configured like:
207 * plugin.tx_myextension._LOCAL_LANG.languageKey.key = value
208 *
209 * @param string $extensionName
210 */
211 protected static function loadTypoScriptLabels($extensionName)
212 {
213 $configurationManager = static::getConfigurationManager();
214 $frameworkConfiguration = $configurationManager->getConfiguration(ConfigurationManagerInterface::CONFIGURATION_TYPE_FRAMEWORK, $extensionName);
215 if (!is_array($frameworkConfiguration['_LOCAL_LANG'])) {
216 return;
217 }
218 self::$LOCAL_LANG_UNSET[$extensionName] = [];
219 foreach ($frameworkConfiguration['_LOCAL_LANG'] as $languageKey => $labels) {
220 if (!(is_array($labels) && isset(self::$LOCAL_LANG[$extensionName][$languageKey]))) {
221 continue;
222 }
223 foreach ($labels as $labelKey => $labelValue) {
224 if (is_string($labelValue)) {
225 self::$LOCAL_LANG[$extensionName][$languageKey][$labelKey][0]['target'] = $labelValue;
226 if ($labelValue === '') {
227 self::$LOCAL_LANG_UNSET[$extensionName][$languageKey][$labelKey] = '';
228 }
229 } elseif (is_array($labelValue)) {
230 $labelValue = self::flattenTypoScriptLabelArray($labelValue, $labelKey);
231 foreach ($labelValue as $key => $value) {
232 self::$LOCAL_LANG[$extensionName][$languageKey][$key][0]['target'] = $value;
233 if ($value === '') {
234 self::$LOCAL_LANG_UNSET[$extensionName][$languageKey][$key] = '';
235 }
236 }
237 }
238 }
239 }
240 }
241
242 /**
243 * Flatten TypoScript label array; converting a hierarchical array into a flat
244 * array with the keys separated by dots.
245 *
246 * Example Input: array('k1' => array('subkey1' => 'val1'))
247 * Example Output: array('k1.subkey1' => 'val1')
248 *
249 * @param array $labelValues Hierarchical array of labels
250 * @param string $parentKey the name of the parent key in the recursion; is only needed for recursion.
251 * @return array flattened array of labels.
252 */
253 protected static function flattenTypoScriptLabelArray(array $labelValues, $parentKey = '')
254 {
255 $result = [];
256 foreach ($labelValues as $key => $labelValue) {
257 if (!empty($parentKey)) {
258 if ($key === '_typoScriptNodeValue') {
259 $key = $parentKey;
260 } else {
261 $key = $parentKey . '.' . $key;
262 }
263 }
264 if (is_array($labelValue)) {
265 $labelValue = self::flattenTypoScriptLabelArray($labelValue, $key);
266 $result = array_merge($result, $labelValue);
267 } else {
268 $result[$key] = $labelValue;
269 }
270 }
271 return $result;
272 }
273
274 /**
275 * Returns instance of the configuration manager
276 *
277 * @return \TYPO3\CMS\Extbase\Configuration\ConfigurationManagerInterface
278 */
279 protected static function getConfigurationManager()
280 {
281 if (!is_null(static::$configurationManager)) {
282 return static::$configurationManager;
283 }
284 $objectManager = GeneralUtility::makeInstance(ObjectManager::class);
285 $configurationManager = $objectManager->get(ConfigurationManagerInterface::class);
286 static::$configurationManager = $configurationManager;
287 return $configurationManager;
288 }
289
290 /**
291 * @return \TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController
292 */
293 protected static function getTypoScriptFrontendController()
294 {
295 return $GLOBALS['TSFE'];
296 }
297
298 /**
299 * @return \TYPO3\CMS\Lang\LanguageService
300 */
301 protected static function getLanguageService()
302 {
303 return $GLOBALS['LANG'];
304 }
305 }