[TASK] Add Introduction and Overhaul Localization API Chapters (#6040)

* [TASK] Add Introduction and Overhaul Localization API Chapters

Releases: main, 13.4

* [TASK] Add Introduction and Overhaul Localization API Chapters

Releases: main, 13.4

Author: linawolf

Documentation/ApiOverview/Localization/LocalizationApi/Index.rst

@@ -1,13 +1,49 @@
-.. include:: /Includes.rst.txt
-.. index::
-   pair: Localization; API
+..  include:: /Includes.rst.txt
+..  index::
+    pair: Localization; API
+..  _localization-api:
 
 ================
 Localization API
 ================
 
+The Localization API provides the building blocks TYPO3 uses to resolve locales
+and translate labels from XLIFF files in both Backend and Frontend code. It
+covers locale parsing and normalization, creation of context-aware translation
+services, and convenient helpers for TypoScript, Extbase and Fluid.
+
+..  card-grid::
+    :columns: 1
+    :columns-md: 2
+    :gap: 4
+    :class: pb-4
+    :card-height: 100
+
+    ..  card:: `Locale <https://docs.typo3.org/permalink/t3coreapi:locale-api>`_
+
+        Parse and normalize IETF BCP 47 language tags (e.g. `de-CH`) to build a
+        precise locale context for translations.
+
+    ..  card:: `LanguageServiceFactory <https://docs.typo3.org/permalink/t3coreapi:languageservicefactory-api>`_
+
+        Create context-aware `LanguageService <https://docs.typo3.org/permalink/t3coreapi:languageservice-api>`_ instances
+        at runtime.
+
+    ..  card:: `LanguageService <https://docs.typo3.org/permalink/t3coreapi:languageservice-api>`_
+
+        Translate labels via `LLL:EXT:...` in PHP; loads XLIFF resources on demand.
+
+    ..  card:: :ref:`LocalizationUtility (Extbase) <extbase-localization-utility-api>`
+
+        Convenience wrapper to translate labels inside Extbase.
+
+    ..  card:: `Localization in TypoScript <https://docs.typo3.org/permalink/t3coreapi:extension-localization-typoscript>`_
+
+        Using `LLL:EXT:...` labels in TypoScript.
+
 ..  toctree::
     :titlesonly:
     :glob:
+    :hidden:
 
     *

Documentation/ApiOverview/Localization/LocalizationApi/LanguageService.rst

@@ -6,18 +6,21 @@ LanguageService
 ===============
 
 This class is used to translate strings in plain PHP. For examples
-see :ref:`extension-localization-php`. A :php:`LanguageService` **should not**
+see :ref:`extension-localization-php`. A
+:php-short:`\TYPO3\CMS\Core\Localization\LanguageService` **should not**
 be created directly, therefore its constructor is internal. Create a
-:php:`LanguageService` with the :ref:`LanguageServiceFactory-api`.
+:php-short:`\TYPO3\CMS\Core\Localization\LanguageService` with the
+:ref:`LanguageServiceFactory-api`.
 
 In the backend context a :php:`LanguageService` is stored in the global
 variable :php:`$GLOBALS['LANG']`.
-In the frontend a :php:`LanguageService` can be accessed via the contentObject:
-
-..  include:: _LanguageService.rst.txt
-
-Example: Use
-========
+In the frontend a :php-short:`\TYPO3\CMS\Core\Localization\LanguageService` can
+be accessed via the contentObject:
 
 ..  literalinclude:: _ExampleController.php
     :caption: EXT:my_extension/Classes/Controller/ExampleController.php (not Extbase)
+
+In CLI context `$GLOBALS['LANG']` is also not available and has to be
+instantiated manually.
+
+..  include:: _LanguageService.rst.txt

Documentation/ApiOverview/Localization/LocalizationApi/LanguageServiceFactory.rst

@@ -5,7 +5,8 @@
 LanguageServiceFactory
 ======================
 
-This factory class is for retrieving the :ref:`LanguageService <LanguageService-api>`
+The :php:`\TYPO3\CMS\Core\Localization\LanguageServiceFactory` class is
+for retrieving the :ref:`LanguageService <LanguageService-api>`
 at runtime, which then is used to translate strings in plain PHP. For examples
 see :ref:`extension-localization-php`. Creates a :ref:`LanguageService-api`
 that can then be used for localizations.

Documentation/ApiOverview/Localization/LocalizationApi/Locale.rst

@@ -50,16 +50,11 @@ object for translations:
 ..  literalinclude:: _LocaleExample.php
     :caption: EXT:my_extension/Classes/LocaleExample.php
 
-
 ..  _IETF RFC 5646: https://www.rfc-editor.org/rfc/rfc5646.html
 ..  _ISO 639-1: https://en.wikipedia.org/wiki/ISO_639-1
 ..  _ISO 639-2: https://en.wikipedia.org/wiki/ISO_639-2
 ..  _ISO 3166-1: https://en.wikipedia.org/wiki/ISO_3166-1
 ..  _ISO 15924: https://en.wikipedia.org/wiki/ISO_15924
 ..  _tags and subtags: https://www.rfc-editor.org/rfc/rfc5646.html#section-2
 
-
-API
-===
-
 ..  include:: _Locale.rst.txt

Documentation/ApiOverview/Localization/LocalizationApi/LocalizationUtility.rst

@@ -5,7 +5,8 @@
 LocalizationUtility (Extbase)
 =============================
 
-This class is used to translate strings within Extbase context. For an example
+The :php:`TYPO3\CMS\Extbase\Utility\LocalizationUtility` class is used to
+translate strings within Extbase context. For an example
 see :ref:`extension-localization-extbase`.
 
 ..  include:: _LocalizationUtilityApi.rst.txt