This seemed the logical place to do it, because it's essentially
a presentation thing (so in Template, not Locale). There's likely
something to be said for sorting by key aswell as sorting by
translated language name. Picked key for now, seems most predictable.

setupTwigTemplatepaths() cannot return false

This can be used by templates to load resources in different ways, either optimized for the developer or for a production environment.

This allows us to use this new filter to translate strings from a given array of translations, where every translation is indexed by its ISO 639 code. A new configuration option ('language' -> 'priorities') is available too to control the alternative languages that can be used instead of a given language, when the latter is not found. The filter returns null when no suitable translation is found, so that it can be combined with "default()" to set a default translation for a given string.

This resolves #695.

Otherwise, a theme would not be able to include/embed/extend its own templates.

This new interface allows themes to define a class that can be hooked at certain specific points of template initialization/handling, so that they can do stuff like automatically adding variables for all templates, or adding twig extensions. This classes must implement the new TemplateControllerInterface, and be specified in the "theme.controller" configuration option. This way, we avoid the performance hit if we use traditional hooks, and we also avoid hooks from other modules causing trouble.

For now, the interface offers two entry points: setUpTwig(), which allows managing the twig environment after initialization (e.g. to add an extension or define filters); and display(), which offers all the data passed to the template, and allows adding or modifying it.

This makes sense as those should be static values available to every template.

Additionally, add a "templateId" variable that we can use for templates to identify themselves.

Make sure if we are using a theme, its module is added as a valid domain where we can look for translations.

It has also an impact in performance, and covers an unlikely scenario. Instead, if you plan to use templates from another module, now you need to call the "addTemplatesFromModule()" method right after creating the template. That way you can register manually what templates you are supposed to use, being much more efficient.

An alternative way to inject data in the templates should be used. This has a terrible impact in performance, and could have undesired side effects.

This allows template users to use their own twig extensions if they want, while also allowing us to remove the "twigInit" hook. Hooks come at a price, and it doesn't make much sense to use them in this case, as they would only be useful if a module wants to add a twig extension even if the code instantiating SimpleSAML_XHTML_Template does not belong to that module. This could lead to unexpected behaviour (i.e. a module adding a hook that creates trouble for the templates defined in another module), so given the lack of use cases supporting the hook and the possible negative consequences implied, it's better to remove it.

This way we we allow those writing themes to use twig extensions, filters, or anything they may need.

This allows custom themes to inject data for all templates by simply adding a new hook.

Make the language parameter name available to the templates, and remove that parameter from the queryParams entry in the template data.

This allows us to focus on the “real” parameters, ignoring language selection routines. It also allows us to build our own language bar the way we want it, not only with links.

This allows us to build the language switching links even when we have query parameters that would otherwise get lost.

Add a couple of methods to perform translations with PHP's native gettext implementation, and start using them.

Since the class names were prepended with "\", the original extension was used, instead of our own wrapper. This fixes that issue, and sets the two new methods in SimpleSAML\Locale\Translate as the functions to use to replace the calls to gettext() and ngettext(). Support for the old translation system is still missing for twig templates.

Define SimpleSAML\XHTML\Template::$twig as a property (previously only set in the constructor) and make sure we use proper type checking when using it.

This makes instanciating the Translate/Template-class unnecessary.