[IDEA] How to do better on localization?

[michaelkubina]

Apologies to the long text upfront...but we need to talk a little about architecture here...

Translations/Localizations in Kitodo.Presentation are currently in a quite scattered state and localization management is undocumented.

We have several problems with the way it is now:

• some few controller use the translate helper method of the Helper Utility class, to output translated text to the view
• this translate() helper function is actually a performance hog (lazy loading a single entry at once, multiple sql queries per entry, etc), which is why we will provide a bugfix for it in the coming days...so this will not be a problem anymore
• but the utility class handles many different things, with localization (metadata, structures, but also language-codes) being one of them... it's bloating the utility class
• other controller handle translations via translation files (in the templates via the fluid viewhelper), but this leads to user created records (in the repositories) not being translated at all, since they are not present in the language files.
• viewhelper invocations have a performance overhead, that can get quite significant (e.g. about 0.2ms on a 1ms calculation -> tested!), when done repeatedly which really adds up

We would like to reduce complexity and have a straight forward localization workflow for Kitodo.Presentation. But this requires some changes:

Purpose of translation files?

We need to make clear, what purpose translation files serve:

• We have translation files, that are only relevant for frontend/backend - like Plugin Settings & descriptions, alternative Texts for Navigation elements in the UI. Those are static translations used everywhere and utilizing the language files here is the way to go.
• We have translation files, that serve as a blueprint when creating new storage folders - populating them via "New Tenant" and said presets. Once the records have been created, they "serve no purpose" anymore ...this is because users can create new records on their own in the backend and we need to take the actual translations from those repositories now. Translation files do not work here anymore ... these are dynamic translations we are handling. Translating these records in the view should not be handled by translation files but by other means.

This means, we cannot use translation files user generated content in our templates.

How to use translations?

• there is no clear guide, on how to set up Kitodo.Presentation correctly in a multilingual setup. We should provide a precise description on how to achieve a multilingual portal.
• Aspects are site_languages, New Tenant usage, page translations of storage folder and pages (also those with plugins), language comparison and the usage of the wizard to achieve connected mode, creating new records and translating them in the repositories

How to make translation handling ubiquitous in code?

Currently we outsource business logic (specifically the handling of dynamic translations) into the templates - except where we dont, because we saw it as being required in the controller. So we are handling translations in two ways already.... Core isse: Invoking fluids translation viewhelper cannot translate dynamic content. So we do need to adress this either by or in combination with:

• a custom viewhelper, that translated dynamic content (metadata, collections, etc.) that uses the actual translate() helper method, at the cost of overhead and business logic being still present in the views. This should be easy to achieve.
• translating dynamic translations directly in the controller and sending the output to the view (as its done in a few places). Business logic would be where it should be, less overhead (viewhelper invocations). this was done in the table of contents controller, and this was actually the right way. only the helper method was not optimized for this task
• outsourcing translation logic from the Helper class into a dedicated translation service, that could be injected into the controllers. This would debloat the helper class and be a modern approach

Which way do we choose?

• it is clear that we need some sort of a guide or tutorial on how to handle translations
• shall we create a viewhelper first for a quick fix, so that we can handle dynamic translations properly, where language files are used now?
• or do we want to translate in the controllers instead and remove translation handling of dynamic translations from the view -> templates simply output the pre-translated text?
• do we want to restructure our codebase, so that we use utililize typo3 service containers more? translations would very well fit in such a pattern

With where things are going, we need to have a robust architecture in place. Currently we are already struggeling with those few translations we are handling. We will likely need more once we translate licences, access policies to resources, restrictions, call to actions, etc....