Using Dictionary Items in XSLT

Written by Chriztian Steinmeier.
Got comments? I’m @greystate on Twitter. ← Back to Article Index

Prerequisites

To use the Dictionary we need to do a couple of things first:

1. We should create the languages we need (Settings > Languages)
2. We need to assign a Domain & Language to the top-level node(s) in our website

When that’s done, we can go ahead and create some Dictionary Items for use in our site.

The Simplest Thing That Could Possibly Work

In short, if you’ve created a Dictionary Item called “SearchTitle”, you can get the localized version of that item using the GetDictionaryItem() method in umbraco.library - like this:

Umbraco will decide which language the current request belongs to and pick the assigned value for the key “SearchTitle”, which it will return to the XSLT.

This is all fine and dandy, and you can fetch any Dictionary Item you’ve created using this call, but soon your code will start to look like it could use a good refactoring. I’d say that if you’re fetching more than a few items you should start to get that “Um, I guess it must be possible to not call that library function all the time…” feeling…

Refactor & Pluralize!

So apparently the Core team got that feeling too and decided to give us (totally free of course) a way to fetch more than one Dictionary Item at a time, by creating the GetDictionaryItems() method. Good call.

It works like this: In the Dictionary you create some items below a top-level item, e.g.:

Dictionary
    SearchLabels
        SearchTitle
        SearchButtonText
        SearchFieldPlaceholder

When you call the pluralized method with the key “SearchLabels” you get the following XML back:

You should of course put that into a variable so you have access to all the labels returned:

OK, That Didn’t Help

While this will make sure that we only call the library funtion once, it won’t exactly make our code look less cluttered:

But of course there’s a way around that - but first a little detour.

Managing Lots Of Dictionary Items

You may already have tried to create a bunch of Dictionary Items, nested in a couple of levels, and subsequently tried to fetch them all in one swoop with the GetDictionaryItems() method. Then you’ve also encountered the limitation/feature of it not returning more than one level of items, i.e., you can only access the children of an item, neither grandchildren nor grandchildren’s children etc.

What I do is to structure the Dictionary Items below one level of “headers”, so the first level of items are all wrappers for the items under them. This makes it pretty easy to organize the items in sections that match the pages they’re used in.

But we need to have easy access to them from XSLT. Enter secret weapon #4815162342 - joining nodesets…

Let’s say I have three sections of Dictionary Items; “Frontpage”, “Search” and “Products”.

What I do in XSLT is this:

By way of making the individual variables select just the DictionaryItem elements, the resulting $labels variable can be used simply like this to get any label from the three sets:

Happiness prevails in my code now - I’m down to saying “Give me the label with the key ‘SearchButtonText’” and no excess calls to umbraco.library.

Hey, What About The Bonus???

Bonus? Oh yes, how could I forget :-)

Well, if you’re processing some custom XML or you’ve named your Dictionary Items after the properties on a Document Type, you can use a “moded template” to handle some of your labels.

The template looks like this:

Then if you have a NewsItem DocumentType with a newsDate property, you could use it like this to get the translated value for the ‘Date’ label:

These kinds of abstractions definitely suit my person well — your milage may vary, as they say, but nevertheless I hope you’ve enjoyed another article, and that you’ll continue to improve your XSLT skills every day.