Dictionaries in FirstSpirit
When you need to publish multi-lingual websites you are frequently faced with the need to provide translations for terms that are not exactly editorial content. These terms are mostly labels that are used throughout the site - in forms ("name", "street", "submit"), search result pages ("We found xx pages that contain your search term"), as navigational items ("back to top of page", "print view") and more.
Wouldn’t it be convenient to have a dictionary that contains all these expressions and their respective translations in all of your websites’ available languages? And provide just the right translation for your website in the appropriate place without the editors having to worry about it? Well - you can! In this article we will show you how to set up a dictionary in FirstSpirit and use it for your purposes.
Technically we are going to store the dictionary entries in a database and make them globally available during the generation of the project so that your templates can use the terms as desired. Let’s walk through this scenario step by step.
Preparing the Database
Next we are going to code the Template and create the Database Node. Not much magic here - you basically only need to provide the input components for the columns and make sure that you don’t forget the mapping!
Making the data available
In order to be able to retrieve the entries we are going to set up a map that contains all database items referenced by key. This is done in the output channel of the project settings (a channel that is rarely used in projects). The necessary code looks like this:
<CMS_HEADER>
<CMS_FUNCTION name="contentSelect" resultname="fr_dictionary">
<CMS_PARAM name="schema" value="projectschema" />
<QUERY entityType="Dictionary"/>
</CMS_FUNCTION>
</CMS_HEADER>
$CMS_SET(dictionary,{"":""})$
$CMS_FOR(entity,fr_dictionary)$
$CMS_SET(void,dictionary.put(entity.key,entity.translation)$
$CMS_END_FOR$
This creates a simple key-value map which is globally available during generation. As it holds only Strings the impact on memory consumption is also very low. As a result of this simple piece of code you can spurt out dictionary entries in every template in the project by using this Code:
$CMS_VALUE(dictionary.get("..key.."))$ There is no need to specify the desired output language - the correct translation will be chosen automatically. So whether you want to fill a drop-down list of countries for a form or just provide some basic labels on your page you are all set to go.
A note on keys
As experience shows it is advisable to use keys that are hierarchichally structured and give information about the field of use for the dictionary entry, such as form.label.firstname or navigation.top - this makes it easier to put dictionary terms into context (and if you sort them by key you can easily see what terms you have covered in a certain field).
Advantages
With a dictionary like this you keep all your terms in one place - and wherever they are used the same translation will be applied. No more "back", "last page", "go back" (and whatever other alternative might come up) to worry about, but just one single expression that is consistently used throughout your site. Also if you add additional languages to your project you can just run an export of the dictionary table, send it to your translation agency and rest assured that you have all your terms covered.
Attached to this post is a small project that gives you a sample implementation. I hope you enjoyed this little tip - As usual post your questions and remarks right here in the comments section. We are happy to receive your feedback.