-
Notifications
You must be signed in to change notification settings - Fork 0
Dev notes #3
Symphony 2.3 comes with a new localisation system that allows translators to provide different translations for the same string, according to the given context.
But what's a context? A Symphony context is a string that tells you which backend page you are currently browsing. The syntax is path-like, so if we're inside the Datasources main page, the context is /blueprints/datasources, while if we are editing an entry it's /publish. If that sounds familiar to you, it's because the syntax is consistent with delegate subscription.
As you can see, guessing the context is pretty straightforward. Say you are editing an event, what would the context be? Inspired by the last example, I hear you saying "it's /blueprints/events". You couldn't be more right! What if you are inside the login page? Well, this one is a bit trickier, but still intuitive: it's /login. Easy right?
Please note that subpages are not considered as different contexts; in fact, a context is to translations like a namespace is to PHP files. It makes sense to have it only for broader purposes -- you wouldn't want to have a namespace for each single PHP file, would you?
For those who didn't fully grasp the logic, just have a look at the relative path of the page URL. It will nonchalantly tells you the answer in 99% of the cases. The only rule here is to ignore subpages, but that's an easy one.
Now that we introduced contexts, you as a developer might be wondering how this affects your everyday job. Well, the answer is... it doesn't affect it at all! The translator function, __(), stays the same -- no extra params added. It's Symphony responsibility, not yours. We designed it to be that way.
On the other hand, if you are a translator you probably want to know how to exploit contexts to provide more accurate translations.
Remember that $dictionary array in your lang.??.php file? In the past for each key in the array (the original string) you could supply a translation as a new string. With the new changes, a $dictionary key is either the string to translate or the a context, and the value is respectively a string or an array of key => value context-aware translations. Example:
$dictionary = array(
'Create New' => 'Crea nuovo',
'/blueprints/datasources' => array(
'Create New' => 'Crea nuova sorgente dati',
),
);
The syntax reads pretty good and hopefully doesn't give rise to misunderstandings. If you're already familiar with multi-dimensional arrays, you're halfway there.
Please note that the order in which keys appears it's not important; Symphony will always looks at context-aware translations first. If no translations are provided for the current context, it climbs the array looking for a context-less version. If no matches are found, it simply returns the original string. Simple as it sounds.
A final note about backward compatibility with 2.2.x; all 2.2.x translations will continue to work and as long as they work they shouldn't be changed. We just offer a new option, not a new task. Thus, if you think your translation is already accurate, you don't have to change anything at all!
That's all for now, a more comprehensive article will be published as soon as Symphony 2.3 lands. Stay tuned for updates and don't miss the next episode of Dev Notes.