From d90969369b47594ff3c9415735c4e7369a0b4d8b Mon Sep 17 00:00:00 2001
From: Lina Wolf <48202465+linawolf@users.noreply.github.com>
Date: Thu, 11 Dec 2025 20:08:12 +0100
Subject: [PATCH] [TASK] Raise deprecation error on using deprecated labels
Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/1511
---
.../Appendix/HowToDeprecateThings.rst | 33 +++++++++++++++----
1 file changed, 27 insertions(+), 6 deletions(-)
diff --git a/Documentation/Appendix/HowToDeprecateThings.rst b/Documentation/Appendix/HowToDeprecateThings.rst
index a151635..bd25a9f 100644
--- a/Documentation/Appendix/HowToDeprecateThings.rst
+++ b/Documentation/Appendix/HowToDeprecateThings.rst
@@ -1,3 +1,5 @@
+:navigation-title: How to deprecate
+
.. include:: /Includes.rst.txt
.. index::
@@ -6,7 +8,7 @@
.. _deprecations:
========================================================================
-How to deprecate classes, methods, arguments and hooks in the TYPO3 core
+How to deprecate classes, methods, arguments and hooks in the TYPO3 Core
========================================================================
TYPO3 Core development policy states that public API will not be changed
@@ -257,17 +259,36 @@ Deprecate a language label reference
If you move or remove a language label from the Core, third-party extensions and
projects may still depend on it. Therefore, it is good practice to keep the original label
-and mark it as deprecated with an ``x-unused-since`` attribute:
+and mark it as deprecated with an `x-unused-since` attribute for XLIFF 1.2 or the
+`subState="deprecated"` property for XLIFF 2.0 files:
+
+.. tabs::
+
+ .. group-tab:: XLIFF 1.2
-.. code-block:: xml
+ .. code-block:: xml
+
+
+ Type
+
-
- Type
-
+ .. group-tab:: XLIFF 2.0
+
+ .. code-block:: xml
+
+
+
+ This is label #5 (deprecated in English)
+
+
The label can then be completely removed in the next major TYPO3 version (the
label must not be referenced any longer in the Core.)
+A deprecation warning is triggered the first time a deprecated label is written
+to the cache. Subsequent resolutions of the same label use the cached entry and do
+not trigger additional warnings until the cache is cleared.
+
Note that some label references use computed label strings, so check
these carefully before removal.