TYPO3-Documentation
diff --git a/‎Documentation/ApiOverview/Localization/ManagingTranslations.rst‎
Lines changed: 83 additions & 103 deletions b/‎Documentation/ApiOverview/Localization/ManagingTranslations.rst‎
Lines changed: 83 additions & 103 deletions
diff --git a/‎Documentation/ApiOverview/Localization/TranslationServer/Crowdin/Faq.rst‎
Lines changed: 36 additions & 0 deletions b/‎Documentation/ApiOverview/Localization/TranslationServer/Crowdin/Faq.rst‎
Lines changed: 36 additions & 0 deletions
@@ -1,29 +1,32 @@
+:navigation-title: Translation management
+
 ..  include:: /Includes.rst.txt
 ..  index:: Localization; Manage translations
 ..  _managing-translating:
 
-=====================
-Managing translations
-=====================
+==============================
+Managing translations in TYPO3
+==============================
 
-This sections highlights the different ways to translate and manage XLIFF files.
+This section highlights the different ways to translate and manage TYPO3
+language files (XLIFF 1.2 and 2.x).
 
+..  contents:: Table of contents
 
 ..  index:: Localization; Fetch translations
 ..  _xliff-translating-fetch:
 
-Fetching translations / updating language packs
-===============================================
+Fetching translations or updating language packs
+================================================
 
 The backend module :guilabel:`Admin Tools > Maintenance > Manage Language Packs`
-displays a list of available languages to your users and can fetch and
-update language packs in TER and Core extensions from the official translation server.
-The module is rather straightforward to use and should be pretty much self-explanatory.
-Downloaded language packs are stored in the environment's
-:ref:`Environment-labels-path`.
+displays a list of available languages and can fetch or update language packs
+for system and extension translations from the official TYPO3 translation server.
 
-..  include:: /Images/AutomaticScreenshots/AdminTools/ManageLanguagePacks.rst.txt
+The module is straightforward to use. Downloaded language packs are stored in the
+environment’s :ref:`Environment-labels-path`.
 
+..  include:: /Images/AutomaticScreenshots/AdminTools/ManageLanguagePacks.rst.txt
 
 Language packs can also be fetched using the command line:
 
@@ -43,14 +46,14 @@ Language packs can also be fetched using the command line:
 
 ..  _load-language-pack:
 
-Load an additional language pack
-================================
+Loading an additional language pack
+===================================
 
-Additional language packs can be installed by administrators in the backend:
+Administrators can install additional language packs directly in the backend:
 
 ..  rst-class:: bignums
 
-1.  Go to :guilabel:`Admin Tools > Maintenance > Manage Languages Packs`
+1.  Go to :guilabel:`Admin Tools > Maintenance > Manage Language Packs`
 
     ..  include:: /Images/AutomaticScreenshots/Modules/ManageLanguage.rst.txt
 
@@ -62,108 +65,91 @@ Additional language packs can be installed by administrators in the backend:
 
     ..  include:: /Images/AutomaticScreenshots/Modules/ManageLanguagePacksAddLanguageAddSuccess.rst.txt
 
+
 ..  index:: Localization; Local translations
 ..  _xliff-translating-local:
 
-Local translations
-==================
-
-With `t3ll <https://github.com/garfieldius/t3ll>`__ it is possible to translate
-XLIFF files locally. t3ll is an open source, cross-platform application and runs
-on console under Linux, MacOS and Windows. It opens its editor inside a Google
-Chrome or Chromium window.
-
-..  figure:: /Images/ExternalImages/System/t3ll.png
-    :alt: t3ll screenshot
-
-    Translating with t3ll
-
-Just call on a console, for example:
-
-..  tabs::
-
-    ..  group-tab:: Linux / MacOS
-
-        ..  code-block:: bash
-
-            t3ll path/to/your/extension/Resources/Private/Language/locallang.xlf
+Translating XLIFF files locally
+===============================
 
-    ..  group-tab:: Windows
+You can translate TYPO3 XLIFF files directly in your development environment
+using any XML or translation editor that supports the XLIFF format.
 
-        ..  code-block:: powershell
+TYPO3 v14 and newer support both **XLIFF 1.2** and **XLIFF 2.x**:
 
-            t3ll.exe path\to\your\extension\Resources\Private\Language\locallang.xlf
+-  **XLIFF 2.x:** uses `<unit>` elements and the `<target state="…">` attribute
+   (`state="reviewed"` / `state="final"` = approved)
+-  **XLIFF 1.2:** uses `<trans-unit>` and the `approved="yes"` attribute
 
-Translating files locally is useful for extensions which should not be published
-or for creating :ref:`custom translations <xliff-translating-custom>`.
+Both formats are automatically detected and parsed by TYPO3.
 
+You can use any text or translation editor to modify `.xlf` files locally.
+Ensure that your chosen tool supports the XLIFF 2.x format, which is the
+default for TYPO3 v14 and later.
 
 ..  index:: Localization; Custom translations
 ..  _xliff-translating-custom:
 
-Custom translations
-===================
+Overriding or extending translations
+====================================
 
 ..  versionchanged:: 14.0
     `$GLOBALS['TYPO3_CONF_VARS']['SYS']['locallangXMLOverride']` has been moved
     to `$GLOBALS['TYPO3_CONF_VARS']['LANG']['resourceOverrides'] <https://docs.typo3.org/permalink/t3coreapi:confval-globals-typo3-conf-vars-lang-resourceoverrides>`_.
 
 Option `$GLOBALS['TYPO3_CONF_VARS']['LANG']['resourceOverrides'] <https://docs.typo3.org/permalink/t3coreapi:confval-globals-typo3-conf-vars-lang-resourceoverrides>`_
-allows overriding XLIFF files. This applies not only to translations but
-also to default language files.
+allows overriding XLIFF files. This applies to both translations and default
+(language = English) files.
 
-..  literalinclude:: _ext_localconf.php
+..  literalinclude:: _snippets/_ext_localconf.php
     :language: php
     :caption: EXT:examples/ext_localconf.php
 
-The German language file looks like this:
+The German language file could look like this:
 
-..  literalinclude:: _de.locallang_modadministration.xlf
+..  literalinclude:: _snippets/_de.locallang_modadministration.xlf
     :language: xml
     :caption: EXT:examples/Resources/Private/Language/Overrides/de.locallang_modadministration.xlf
 
+TYPO3 loads either XLIFF 1.2 or 2.x — the format is detected automatically.
 
-and the result can be easily seen in the backend:
+The result can be seen in the backend:
 
 ..  figure:: /Images/ManualScreenshots/Internationalization/InternationalizationLabelOverride.png
     :alt: Custom label
 
     Custom translation in the TYPO3 backend
 
-
 ..  attention::
-    -   You do not have to copy the full reference file, but only the labels you
-        want to translate.
+    -   You only need to include the labels you want to override.
     -   The path to the file to be overridden must be specified as
-        :file:`EXT:my_extension/...` and have the extension `xlf`.
+        :file:`EXT:my_extension/...` and must end with `.xlf`.
 
 ..  attention::
-    The following is a **bug** but must be taken as a constraint for now:
+    The following is a **known limitation**:
 
-    -   The files containing the custom labels must be located inside an
-        extension. Other locations will not be considered.
-    -   The original translation needs to exist in the environment's
+    -   Custom label files must be located inside an extension.
+        Other locations are ignored.
+    -   The original translation must exist in the environment’s
         :ref:`Environment-labels-path` or next to the base translation file in
-        extensions, for example in
+        the extension, for example in
         :file:`my_extension/Resources/Private/Language/`.
 
 
 ..  index:: Localization; Custom languages
 ..  _xliff-translating-languages:
 
-Custom languages
-================
+Adding custom languages
+=======================
 
-TYPO3 :ref:`supports many languages <i18n_languages>` by default. But it is also
-possible to add custom languages and create the translations locally using XLIFF
-files.
+TYPO3 :ref:`supports many languages <i18n_languages>` by default, but you can also
+add custom languages and provide your own translations using XLIFF 1.2 or 2.x.
 
 ..  rst-class:: bignums-xxl
 
 #.  Define the language
 
-    As example, we "gsw_CH" (the official code for “Schwiizertüütsch” - that is
-    "Swiss German") as additional language:
+    Example: add "gsw_CH" (Swiss German) as an additional language.
 
     ..  code-block:: php
         :caption: config/system/additional.php | typo3conf/system/additional.php
@@ -174,9 +160,9 @@ files.
 
 #.  Add fallback to another language
 
-    This new language does not have to be translated entirely. It can be defined
-    as a fallback to another language, so that only differing labels have to be
-    translated:
+    This language does not have to be translated completely.
+    It can fall back to another language so that only differing labels
+    need translation.
 
     ..  code-block:: php
         :caption: config/system/additional.php | typo3conf/system/additional.php
@@ -185,49 +171,43 @@ files.
             'gsw_CH' => ['de_AT', 'de'],
         ];
 
-    In this case, we define that "gsw_CH" can fall back on "de_AT" (another
-    custom translation) and then on "de".
+    In this example, "gsw_CH" falls back to "de_AT" and then to "de".
 
 #.  Add translation files
 
-    The translations for system extensions and extensions from :abbr:`TER (TYPO3
-    Extension Repository)` must be stored in the appropriate labels path
-    sub-folder (:ref:`Environment-labels-path`), in this case :file:`gsw_CH`.
+    Translation files for system and extension labels must be stored under the
+    correct subfolder of the environment’s :ref:`Environment-labels-path`.
+    The minimum requirement is to translate the language name so it appears
+    in the user settings.
+
+    ..  tabs::
+
+        ..  group-tab:: XLIFF 2.0 (recommended)
+
+            ..  literalinclude:: _snippets/_gsw_CH.locallang_2.0.xlf
+                :language: xml
+                :caption: gsw_CH/setup/Resources/Private/Language/gsw_CH.locallang.xlf
 
-    The least you need to do is to translate the label with the name of the language
-    itself so that it appears in the user settings. In our example, this would be in
-    the file :file:`gsw_CH/setup/Resources/Private/Language/gsw_CH.locallang.xlf`.
 
-    ..  code-block:: xml
-        :caption: gsw_CH/setup/Resources/Private/Language/gsw_CH.locallang.xlf
+        ..  group-tab:: XLIFF 1.2 (legacy)
 
-        <?xml version="1.0" encoding="UTF-8"?>
-        <xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2">
-            <file source-language="en" target-language="gsw_CH" datatype="plaintext" original="EXT:setup/Resources/Private/Language/locallang.xlf">
-                <body>
-                    <trans-unit id="lang_gsw_CH" approved="yes">
-                        <source>Swiss German</source>
-                        <target>Schwiizertüütsch</target>
-                    </trans-unit>
-                </body>
-            </file>
-        </xliff>
+            ..  literalinclude:: _snippets/_gsw_CH.locallang_1.2.xlf
+                :language: xml
+                :caption: gsw_CH/setup/Resources/Private/Language/gsw_CH.locallang.xlf
 
-    The custom language is now available in the user settings:
+    The new language is now available in the backend user settings:
 
     ..  include:: /Images/AutomaticScreenshots/Internationalization/CustomLanguage.png.rst.txt
 
-    For translations in own extensions you can provide the custom language files
-    in the :file:`Resources/Private/Language/` folder of the extension, for
-    example :file:`gsw_CH.locallang_db.xlf`.
+    For your own extensions, provide the custom language files in the
+    :file:`Resources/Private/Language/` folder, for example
+    :file:`gsw_CH.locallang_db.xlf`.
 
-..  note::
-    Each language will always fall back on the default one (i.e. English) if no
-    a translation is found. A custom language will fall back on its "parent"
-    language automatically. Thus, in our second example of "de_AT" (German for
-    Austria), there would be no need to define a fallback for "de_AT" if it fell
-    back to "de".
+Each language always falls back on the default one (English) if no
+translation is found. A custom language automatically falls back on its
+defined dependencies. For example, "de_AT" would fall back on "de"
+automatically.
 
 ..  seealso::
-    Configure :yaml:`typo3Language` to use custom languages in the frontend,
-    see :ref:`sitehandling-addinglanguages` for details.
+    Configure :yaml:`typo3Language` to use custom languages in the frontend.
+    See :ref:`sitehandling-addinglanguages` for details.
@@ -46,6 +46,42 @@ Crowdin please contact either the maintainer of the extension or the
 
 ..  _Localization Team: https://typo3.org/community/teams/localization
 
+.  _crowdin-faq-xliff-version:
+
+Why do XLIFF files on Crowdin look different now?
+-------------------------------------------------
+
+TYPO3 v14 and newer can use the modern **XLIFF 2.x** format for translation files.
+This version introduces a cleaner structure with `<unit>` and `<segment>`
+elements and uses the `<target state="…">` attribute instead of the older
+`approved="yes"` attribute used in XLIFF 1.2.
+
+Crowdin supports both formats, and TYPO3 automatically detects which version is
+used — so you do not need to convert files manually.
+
+..  seealso::
+    Learn more about XLIFF 2.x in TYPO3:
+    :ref:`xliff`
+
+..  _crowdin-faq-xliff-convert:
+
+Do I need to convert existing XLIFF 1.2 files to 2.x?
+-----------------------------------------------------
+
+Not necessarily.
+
+-  As long as your extension **still supports TYPO3 13 LTS**, you **must not**
+   switch to XLIFF 2.x, because TYPO3 v13 only supports XLIFF 1.2.
+-  TYPO3 v14 and later can read both XLIFF 1.2 and 2.x files seamlessly.
+-  For **new extensions** that target TYPO3 14 and above, use **XLIFF 2.x**
+   from the start.
+
+Before switching, also check that your **translation workflow and tools**
+(Crowdin integration, offline editors, or automation scripts) are **compatible
+with XLIFF 2.x**. Some older tools might still expect XLIFF 1.2 files.
+
+You can convert existing files manually or by script — see :ref:`xliff` for
+examples — but there is no urgent need to migrate if XLIFF 1.2 works for your project.
 
 ..  _crowdin-faq-pootle: