Extending Core classes with the @internal tag

Question

I need to make weights of Taxonomies translatable and only show translations of terms when you change language.

To do this I need to override the OverviewTerms class from the Taxonomy module to change some of its methods. However, when I try to extend the OverviewTerms class PhpStorm puts a strikethrough on OverviewTerms because it is marked as @internal, although I can still extend and use the new extension.

What does the @internal tag mean and what is the right way to extend classes with this tag?

Answer 1

Drupal 8 and 9 backwards compatibility and internal API policy (backend), linked by @4uk4, states:

Contributed and custom code should avoid calling internal APIs because they might change in minor releases and such changes may not be documented in change records.

To me, the most important point here is such changes may not be documented in change records, meaning that if you extend an @internal class, your code may break, and even if you read the change records for that release, you may not be able to quickly identify the change because the relevant change may not have a change record.

So, the best thing to do is not to extend @internal classes and instead use hooks or extend other classes to achieve the behavior you want. For example, for taxonomy terms, you could try adding the behavior in an entity bundle class.

If you absolutely must extend an @internal class, then you also need to have extensive unit/functional tests of whatever you add, and you need to run those tests every time you update core to ensure nothing breaks.