.. include:: /Includes.rst.txt .. index:: Localization; PHP .. _xliff-api-php: .. _extension-localization-php: =================== Localization in PHP =================== Sometimes you have to localize a string in PHP code, for example inside of a controller or a user function. Which method of localization to use depends on the current context: .. contents:: :local: .. _extension-localization-php-plain: Localization in plain PHP ========================= .. note:: The global variable :php:`$GLOBALS['LANG']` is not available in all contexts so it is best not to rely on it. Use :php-short:`\TYPO3\CMS\Core\Localization\LanguageServiceFactory` instead. The :php-short:`\TYPO3\CMS\Core\Localization\TranslatorInterface` objects are available if a backend user has been initialized, in particular in the following contexts: * frontend: only if there is a logged-in backend user * backend: always, except in :guilabel:`System` modules (for example within an upgrade wizard in the backend) * install tool / install tool modules in backend (e.g. Upgrade Wizard): no * in cli: only if a backend user was initialized, e.g. by :php:`TYPO3\CMS\Core\Core\Bootstrap::initializeBackendUser()` The :php-short:`\TYPO3\CMS\Core\Localization\LanguageServiceFactory` can be used to instantiate. Please see the examples below. :ref:`The methods provided by the instantiated TranslatorInterface ` class then be used to translate texts using the language keys of XLIFF language files. .. _extension-localization-php-frontend: Localization in frontend context -------------------------------- In plain PHP use the class :ref:`LanguageServiceFactory ` to create a :ref:`TranslatorInterface ` from the current site language: .. literalinclude:: _php/MyUserFunction.php :caption: EXT:my_extension/Classes/UserFunction/MyUserFunction.php :ref:`Dependency injection ` should be available in most contexts where you need translations. Also the current request is available in entry point such as custom non-Extbase controllers, user functions, data processors etc. .. _extension-localization-php-backend: Localization in backend context ------------------------------- In the backend context you should use the :ref:`LanguageServiceFactory ` to create the required :ref:`TranslatorInterface `. .. literalinclude:: _php/MyBackendClass.php :caption: EXT:my_extension/Classes/Backend/MyBackendClass.php .. attention:: During development you are usually logged into the backend. So the global variable :php:`$GLOBALS['LANG']` might be available in the frontend. Once logged out it is usually not available. **Never** depend on :php:`$GLOBALS['LANG']` in the frontend unless you know what you are doing. .. _extension-localization-php-without: Localization without context ---------------------------- If you should happen to be in a context where none of these are available, for example a static function, you can still do translations: .. literalinclude:: _php/MyUtility.php :caption: EXT:my_extension/Classes/Utility/MyUtility.php .. _extension-localization-extbase: Localization in Extbase ======================= In :ref:`Extbase ` context you can use the method :ref:`\\TYPO3\\CMS\\Extbase\\Utility\\LocalizationUtility::translate($key, $extensionName) `. This method requires the localization key as the first and the extension's name as optional second parameter. For all available parameters see :ref:`below `. Then the corresponding text in the current language will be loaded from this extension's :file:`locallang.xlf` file. The method :php:`translate()` takes translation overrides from TypoScript into account. See :ref:`Changing localized terms using TypoScript `. .. _extension-localization-extbase-example: Example: translate a flash message in an Extbase controller ----------------------------------------------------------- In this example the content of the flash message to be displayed in the backend will be translated: .. literalinclude:: /ExtensionArchitecture/HowTo/Localization/_php/PhpLocalization.php :caption: Class MyVendor\\MyExtension\\Controller\\ModuleController :emphasize-lines: 30,31,32,33,34 The string in the translation file is defined like this: .. literalinclude:: _php/locallang.xlf :caption: EXT:my_extension/Resources/Private/Language/locallang.xlf :language: xml :emphasize-lines: 8 The :php:`arguments` will be replaced in the localized strings by the `PHP function sprintf `__. This behavior is the same like in a :ref:`Fluid translate ViewHelper with arguments `. .. _example-localization-middleware: Example: provide localized strings via JSON by a middleware =========================================================== In the following example we use the :ref:`Translator API ` to provide a list of localized season names. This list could then be loaded in the frontend via Ajax. You can find the complete example in `GitHub, EXT:examples and HaikuSeasonList `__. As we do not need a full frontend context with TypoScript the JSON is returned by :ref:`PSR-15 middleware `. Beside other factories needed by our response, we inject the :ref:`LanguageServiceFactory ` with :ref:`constructor dependency injection `. .. literalinclude:: /ExtensionArchitecture/HowTo/Localization/_php/_LanguageServiceFactoryDI.php :caption: Class T3docs\\Examples\\Middleware\\HaikuSeasonList The main method :php:`process()` is called with a :php-short:`Psr\Http\Message\ServerRequestInterface` argument that can be used to detect the current language and is passed on to the private method :php:`getSeasons()` to do the actual translation: .. literalinclude:: /ExtensionArchitecture/HowTo/Localization/_php/_ProcessMiddleware.php :caption: Class T3docs\\Examples\\Middleware\\HaikuSeasonList Now we can let the :php:`\TYPO3\CMS\Core\Localization\LanguageServiceFactory` create an object of type :php-short:`\TYPO3\CMS\Core\Localization\TranslatorInterface` from the language in the request, falling back to the default language of the site. The :php-short:`\TYPO3\CMS\Core\Localization\TranslatorInterface` object can then be queried for the localized strings: .. literalinclude:: /ExtensionArchitecture/HowTo/Localization/_php/_LanguageServiceSl.php :caption: Class T3docs\\Examples\\Middleware\\HaikuSeasonList