Symphony 2.3 – Localisation

The Problem

Symphony uses AJAX requests to fetch translations inside JavaScript files. These requests have to be made synchronously to make all translations available before interface components are added to the DOM.

Currently Symphony expects strings to be added on document.ready() because this is when the system knows about the current language. There are two problems:

• If an extensions adds strings to the Dictionary outside document.ready(), each of these calls results in a separate AJAX request (slowing down the backend due to the synchronous nature of these requests).
• If an extension adds strings to the Dictionary inside document.ready(), the system checks for already added strings before sending a request but new strings still result in a separate (although smaller) AJAX request.

In slow server environment this can make the backend unusable. On a client's server it took up to 10 seconds until the backend responded (and that with only a few extensions installed).

The Solution

Symphony 2.3 should change a few things:

• Extension developers are encouraged to always add their strings outside document.ready(). Right on top of each script is a good place.
• Symphony should store all added strings in a private object inside admin.js until the DOM is ready. This means: If Symphony.Context.get('lang') isn't set, Symphony.Language.add() should store the strings.
• Symphony should remove duplicates when storing strings.
• As soon as the document is ready, admin.js should fetch the translations in one synchronous request.

In an ideal world where all developers add their strings before the document is ready, this would only result in one AJAX request. There should of course be no request for English backends.

Handling string additions inside document.ready()

Of course, the world is not ideal, so Symphony should handle calls to Symphony.Language.add() that are made after the DOM is ready (which was the expected behaviour prior Symphony 2.3):

• Symphony should throw an error to the browser console, making clear that strings have to be added before the DOM is ready
• Still, Symphony should fetch the strings in order to keep the backend localised and in order to be backwards compatible. So it should make a separate request to the server and fetch the additional strings. Of course it should check for duplicates first: maybe nothing needs to be translated at all.

The Bonus

To further reduce request to the server, Symphony should store the translations using localStorage. As translations are the same across different Symphony installs, a single storage could be used for all installs:

• Symphony should only fetch strings that are not in the local storage yet.
• If Symphony or any extensions have been updated, the system should set a flag that the local dictionary has to be flushed and replaced with up-to-date strings (e. g. using a data attribute attached to the body: data-translations="flush")
• Before using the translations from localStorage, Symphony's localisation function should check if a special flag is set: If the backend URL contains ?flush the locally stored dictionary should be reloaded from the server. This function is useful during extension development when you need to see updated strings directly.