Reading time: 6 min read
Using Sitecore Dictionaries in XM Cloud: The Right Way, The Wrong Way, and the Creative Way
How to avoid pitfalls and unlock new possibilities with Sitecore dictionaries.
The Overlooked Power of Sitecore Dictionaries
In Sitecore XM Cloud, dictionaries remain a vital tool for managing multilingual UI text in a way that makes sense to content authors and developers alike. They keep language-specific values out of your codebase, make it possible for content authors to adjust labels without a deployment, and ensure your site can truly support a global audience. But with Next.js, there’s more to dictionaries than simply “look up a phrase and render it”, although, you can do just that. In this article, I'm going to walk you through the right way to use dictionaries, the wrong way (that will cause you pain later), and some creative uses that go beyond UI labels. I'll even throw in a few examples.
The Sitecore XM Cloud Dictionary is located within each site and contains two types that you can insert. They are:
- Dictionary entry
- Dictionary folder
Unfortunately, by default, they have the same icon so it can be visually tough to navigate at first.
By default they support multi-language but it’s not entirely necessary to use them in this fashion. It is however, perhaps, the most common usage of dictionaries.
The Right Way of Organizing and Using Sitecore XM Cloud Dictionary Values
The right way to use Sitecore dictionaries in XM Cloud starts with a clear naming convention and version control discipline. I recommend the component-dictionary-key format for component-specific labels, such as hero-banner-title or footer-contact-label. This creates a natural namespace that mirrors your front-end architecture and makes it instantly obvious where a key belongs. For text that’s reused across components, adopt a common-* prefix, like common-read-more or company-name. This gives you a reliable pattern for identifying shared phrases.
I recommend keeping the name of the item the same as the key field value. This allows for quick developer lookup. And when the naming convention is clear, as above, even authors will be able to locate what they are needing to change quickly.
Organizing them in a proper structure is equally important as is the name. However, there are two approaches. The first is my preference where dictionary values are organized according to use. This makes it clear to both authors and developers where the information is used. It does however silo that information and may not be clear how the information could be used outside of the specific component.
Let’s look at what that may look like.
/Components
/EventCard
event-card-register-button
event-card-timezone
event-card-date-format
/HeroBanner
hero-banner-title
hero-banner-cta
/Global
/A
/B
/C
common-read-more
common-submit
company-name
company-tagline
There is however an alternative approach. Treating the Dictionary just like a traditional dictionary. Using this method, all dictionary items would be located within their appropriate alphabetical directory. Such as follows:
/A
/B
blog-category-label
/C
common-read-more
/D
/E
...
As long as the developers are consistent and, how they are used is explained to authors and your client, either approach would suffice.
The Wrong Way to Use Sitecore Dictionaries
A common misuse of Sitecore dictionaries comes from trying to treat them as a general content repository. If a piece of text is frequently updated, heavily managed by authors, or unique to a single page—such as headings, hero text, or long-form content—it does not belong in the dictionary. Those elements should live in standard Sitecore content fields where authors can make updates in context, preview them, and publish through normal workflows.
Dictionaries are designed for values that rarely change, but when they do, need to be updated everywhere on the site at once—things like button labels, form validation messages, or timezone values. If you put constantly changing content into a dictionary, you lose the benefits of page-specific authoring, make content harder to preview, and create unnecessary friction for both authors and developers. In short: if it’s a story headline, it belongs in a content item; if it’s a “Register” button label that appears across hundreds of components, it belongs in the dictionary.
Belongs in a Dictionary
- Reusable UI labels (e.g., “Register”, “Read More”)
- Form field placeholders and validation messages
- Navigation link labels used across the site
- Company name or tagline
- Timezone names and date/time format strings
- Error messages that appear in multiple places
Does NOT Belong in a Dictionary
- Page-specific headings or hero titles
- Article or blog content
- Marketing campaign headlines
- Product descriptions
- Body copy or rich text blocks
- Frequently updated promotional text
Creative Ways to Use Sitecore Dictionary Items
While dictionaries are perfect for multilingual labels and reusable microcopy, they can also be used for more advanced scenarios. One of my favorites is timezone management. Instead of hardcoding timezone names, abbreviations, or offsets, store them in the dictionary. For example, tz-pst might map to “Pacific Standard Time” and tz-est to “Eastern Standard Time.” Paired with localized date formatting keys (date-format-short → “MM/DD/YYYY”), you can ensure your events display correctly for any region without baking formatting logic into your code.
This opens the door to using dictionaries as a content-driven configuration layer. Marketing can update timezone labels, date formats, or even feature labels without a code change, and your components will adapt instantly.
For example, let’s say you want to display a Next.js Event Card component. You could store the following key value pairs in your Sitecore Dictionary.
event-card-timezone: "Pacific Standard Time"
date-format-long: "dddd, MMMM D, YYYY h:mm A"
event-card-register-button: "Register Now!"
And then in the component itself, you could utilize these dictionary values like so.
import { useI18n } from 'next-localization';
import { format, utcToZonedTime } from 'date-fns-tz';
interface EventCardProps {
title: string;
location: string;
description: string;
eventDateUtc: string; // e.g., "2025-08-12T18:00:00Z"
}
const EventCard = ({
title,
location,
description,
eventDateUtc
}: EventCardProps): JSX.Element => {
const { t, locale } = useI18n();
// Retrieve timezone and date format from the dictionary
const timezone = t('event-card-timezone');
const dateFormat = t('date-format-long');
// Convert UTC to the dictionary-defined timezone
const zonedDate = utcToZonedTime(new Date(eventDateUtc), timezone);
const formattedDate = format(zonedDate, dateFormat);
return (
<div className="event-card">
<h2>{title}</h2>
<p><strong>{location}</strong></p>
<p>{description}</p>
<p>
{formattedDate} ({timezone})
</p>
<button>{t('event-card-register-button')}</button>
</div>
);
};
export default EventCard;
Consistency Is Vital
Regardless of how you end up using your Sitecore XM Cloud Dictionary, being consistent in the approach, documenting its usage, that is the most important aspect of the dictionary. Otherwise, it becomes a wasteland and useless information storage repository.