Skip to content

[TASK] Raise deprecation error on using deprecated labels #406

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
linawolf merged 1 commit into from
Dec 11, 2025
Merged

[TASK] Raise deprecation error on using deprecated labels #406

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 27 additions & 6 deletions Documentation/Appendix/HowToDeprecateThings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
:navigation-title: How to deprecate

.. include:: /Includes.rst.txt

.. index::
Expand All @@ -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
Expand Down Expand Up @@ -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

<trans-unit id="CType_formlabel" x-unused-since="14.0">
<source>Type</source>
</trans-unit>

<trans-unit id="CType_formlabel" x-unused-since="14.0">
<source>Type</source>
</trans-unit>
.. group-tab:: XLIFF 2.0

.. code-block:: xml

<unit id="label5">
<segment subState="deprecated">
<source>This is label #5 (deprecated in English)</source>
</segment>
</unit>

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.

Expand Down