umbraco-dictionary-items

Dictionary items

A dictionary item is a keyed string with one value per language, managed by editors under Translation > Dictionary. Use it for static UI text - labels, buttons, headings - not for content: text that varies per language as content belongs in a language-variant property on the Document Type.

Workflow

1. Decide the keys using the dotted naming convention: one parent group item (e.g. Site), children named Group.Thing (Site.ReadMore, Site.Footer.Copyright). Keys are identifiers referenced from code, so treat them like constants and keep one casing; lookups are case-insensitive on Umbraco's default databases, but don't rely on that across environments. Grouping keeps the Translation tree navigable for editors.
2. Create the items in the Translation section - via the Umbraco Developer MCP if available, otherwise by hand following the official Dictionary items guide (create, group, edit; Export/Import of .udt files to move items between sites). If the request is backoffice-only (an editor, no code), fetch that guide and walk the user through its steps dialog by dialog - on import, for example, reviewing the items and choosing where they go - and link the guide in your answer.
3. Render them - open the rendering reference before writing any view code: the exact lookup overloads, the explicit-culture form, null-safe multi-value rendering, and culture handling.
4. Verify, then report - finish with the reference's Verify and Done sections. Don't skip the build check; see the first best practice below for why "it looks right" is not evidence.

Version compatibility

Umbraco 17+. GetDictionaryValue, GetDictionaryValueOrDefault and CultureDictionary are available on Umbraco in any view that inherits UmbracoViewPage, with or without ModelsBuilder. The older ILocalizationService is obsolete and must not be used.

Best practices

• Always have a fallback - with the right overload. GetDictionaryValue(key) returns an empty string for a missing key or translation; use GetDictionaryValueOrDefault(key, fallback) wherever blank UI is unacceptable. It is the only fallback mechanism: a language's configured fallback language applies to content properties, not to dictionary values. Beware the look-alike: GetDictionaryValue(key, "fallback") reads naturally but does not compile - that second parameter is a CultureInfo.
• Let the request culture drive lookups. On a routed front-end request Umbraco sets CurrentUICulture from the matched domain; use the explicit CultureInfo overload only when you deliberately want a fixed culture.
• Single-key lookups are cached; GetChildren is not. CultureDictionary[key] and the GetDictionaryValue* calls are the safe read path for views. CultureDictionary.GetChildren(key) runs a database query per call and drops children with no translation, so keep it out of templates - and never call IDictionaryItemService (the management API) from a view.
• Dictionary = chrome, variants = content. If the text is part of the page's editorial content, it is a language variant, not a dictionary item.

Validation

Documented - this skill ships no code and nothing ran: the Razor snippets in the reference are illustrative and uncompiled, and the Multilanguage setup tutorial is the source for the real thing. Assertions live in evals/evals.json; run them with the umbraco-skill-evaluator skill.