Hi guys, today's episode is all about dictionary items and how you can use them to do powerful stuff with them.

Note: The concepts mentioned in this article works the same in Umbraco version 4, 6. Currently it's not supported in version 7.

The basics

You can create one or more dictionary items in the "Settings" section where you simply just right click the "Dictionary" folder and select to create a new item, just like you create anything else in Umbraco.

An entry for each defined language in your Umbraco instance will show up and you can write a word or whole sentence in the different languages.

When building multi-language sites there is the traditional way, which you can learn more about on umbraco.tv or the 1-1 approach, which was featured in last year's 24 Days In Umbraco calendar.

Get organized

"Wouldn't it be nice if you could organize the items in folders", I hear you saying. Well you can. Kind of! 

It's actually possible to create nested dictionary items, which gives you the opportunity to organize your dictionary items into some more logical structures.

Se the images below - Makes quite a difference, right?

Unorganized structure

Or

Organized structure

"But it's not a real folder", well you're right about that. But since it's possible to nest the items you can create structure and use them as folders. However it's currently hard to visually distinguish between items that are used for holding translated text and those that act like folders.

This is all nice for creating dictionary items that can be used on the website and if you're an XSLT guy then Chriztian "I eat XSLT for breakfast" Steinmeier has written a nice article on using dictionary items in XSLT, which is an enjoyable read.

But did you know that it's actually also possible to translate property names, descriptions etc. that you create to build the user interface within Umbraco? No? Well continue reading then :)

Making the backoffice multi-language

So you have been working on this large multi-language website, which has visitors from many countries around the world and each country has it own language-version of the website.

The websites are being updated by editors from each country and perhaps the editors from Spain and Denmark don't feel too comfortable updating the website, since every property and description is written in english, which you advised the client to be the language of choice, since it's after all easier for spanish and danish people to learn english than it is for english or american people to learn either danish or spanish.

However, some of the editors may not feel too comfortable with the english back-office and would wish it was possible to have the names and description fields setup in their own language.

Well, with Umbraco it's possible to do just that.

(Since I suck at spanish the following examples will be in danish and english.)

So I have this document type, which consists of a header field and a body text field.

I have a description for both fields.

I Start out by Creating a dictionary item called "Back office items", which acts as a folder and then I create another two folder-entries called "Property name items" and "Property description items". 

Under each folder I create the "Header Name", "Header description", "Body text name" and "Body text description" entries, which I'm going to refer to in my document types.

Now when I create my header and description on my Textpage document type I simply just use #Header name, which is the name of the dictionary item for my header text, in the name field. In the description I reference #Header description.

So when I see the text page being logged in with a user set to the english culture, it will look like this:

And when I log in using my danish user account it looks like this:

That's pretty awesome, huh? :) All I do is reference the dictionary name using the hash sign like this: #DictionaryName - really simple, right?

And that's not all!

You can also make translations of

• Document type names
• Tabs 
• Datatypes (Checkbox list, Radio button list and any variation of the drop down list)

Simply add dictionary items for the above mentioned stuff and reference them using #DictionaryName when you create a document type, tab or even a datatype (Based on the ones mentioned above - It may be possible on others as well).

That's pretty cool, huh? Indeed it is, but be aware that extending document types, creating new document types etc. WILL take you longer time than usual because you need to create some dictionary items before creating new properties or document types so make sure it's worth the effort and creates value for your client and editors before going down this road. 

If everyone is fine by the english as a default language then it's perfectly fine to just keep the language in english in general.

Make sure you keep being organized

As you can see from my screen dumps earlier in the article I have made two dictionary folders in the root - One for the website translations called "Website" and one for the back-office translations called "Backoffice". This should help keeping things organized, but if you prefer to organize things different that's of course entirely up to you.

You may also want to create a prefix if you're going to make a package, which should be possible to easily translate into other languages. Then it would make sense to prefix the dictionary items using your package name or a short name of your package.

Before we "Finnish" (-get it? :)) for today, I'd like to mention some things to be aware of when working with dictionary items.

A few things to be aware of

Ok, so now you have learned that you can do some pretty powerful stuff using dictionary items and you're probably going to use it a lot more in upcoming projects. So here's a list of "gotchas" that are nice to know about

Currently it's not possible to

• Rename a dictionary item - So make sure that you write the correct name
• Move dictionary items if you need to restructure for some reason
• Sort dictionary items
• Copy dictionary items
• To create two dictionary items with the same name - Therefore it's a good idea to use prefixes if the same word or sentence needs a unique entry for some reason

And currently the default administrator account has its language set to UK english and the default english language created is US english, which will result in your carefully translated property names etc. will display in the back office like [#PropertyName] - If you would like to have this minor issue fixed in the core, feel free to go and vote it up or even dig into the core and submit a patch fix.

If you would like that to change then you can vote up this improvement suggestion on the issue tracker and add more suggestions if you have an idea to make the dictionary item board better.

Ok, I'm done - Hope you liked it. Now, go and have a play! :)

Merry Xmas and happy holidays everyone.