Backoffice Localization (v18.1): Document type-safe keys for plugin authors#8073
Backoffice Localization (v18.1): Document type-safe keys for plugin authors#8073iOvergaard wants to merge 1 commit into
Conversation
Adds a "Type-safe localization keys" section to the Backoffice
Localization article covering the new compile-time validation in
v18.1+:
- `localize.term()`, `termOrDefault()`, and `<umb-localize key="…">`
are typed against the built-in English dictionary; editors
autocomplete every key, function-valued entries forward their
parameter list for compile-time arg checking.
- Plugin authors can extend the typing with their own keys via plain
`declare global { interface UmbKnownLocalizationSet { … } }` — same
pattern as `UmbExtensionManifestMap`. The type declaration is opt-in;
plugins that skip it still work, they just lose autocomplete and
arg-type checking on their own keys.
Lands the developer-facing half of umbraco/Umbraco-CMS#22887.
|
Thanks for opening this PR! 🎉 Quick question: Does this PR include any AI-generated content? AI tools are absolutely welcome here! We only ask that you follow our AI contribution guidelines to help keep the documentation consistent and trustworthy. Drop a quick comment to let us know! |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| Available from Umbraco 18.1. | ||
| {% endhint %} | ||
|
|
||
| The `localize.term()` and `localize.termOrDefault()` methods, and the `key` attribute on `<umb-localize>`, are typed against the canonical English dictionary that ships with the backoffice. Editors that support TypeScript (VS Code, WebStorm, Rider) autocomplete every known key as you type, and function-valued entries forward their parameter list so calls are checked at compile time: |
There was a problem hiding this comment.
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.
| Available from Umbraco 18.1. | ||
| {% endhint %} | ||
|
|
||
| The `localize.term()` and `localize.termOrDefault()` methods, and the `key` attribute on `<umb-localize>`, are typed against the canonical English dictionary that ships with the backoffice. Editors that support TypeScript (VS Code, WebStorm, Rider) autocomplete every known key as you type, and function-valued entries forward their parameter list so calls are checked at compile time: |
There was a problem hiding this comment.
[UmbracoDocs.Brands] Use 'Visual Studio Code' instead of 'VS Code' for brand consistency.
|
|
||
| ### Adding plugin-specific keys | ||
|
|
||
| Once you have [registered your localization extension](#registering-localization), you can teach the type system about your own keys by extending the global `UmbKnownLocalizationSet` interface from anywhere in your code (same pattern as `UmbExtensionManifestMap`): |
There was a problem hiding this comment.
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.
| this.localize.term('mypkg_greeting', 'Alice'); // 'Alice' checked against (name: string) => string | ||
| ``` | ||
|
|
||
| The type declaration is opt-in — plugins that skip it still work, because the `term()` signature accepts any string. You just lose autocomplete and argument-type checking on the plugin's own keys. |
There was a problem hiding this comment.
[UmbracoDocs.Editorializing] Consider removing 'just' as it can be considered opinionated.
There was a problem hiding this comment.
Pull request overview
Adds documentation for Umbraco CMS v18.1’s type-safe localization key support, aimed at both consumers of the built-in dictionary and plugin authors extending localization key types.
Changes:
- Introduces a new “Type-safe localization keys” section with examples of compile-time validation and IDE autocomplete.
- Documents an escape hatch for dynamically composed localization keys.
- Explains how plugin authors can add their own key typings via global interface merging (
UmbKnownLocalizationSet).
Comments suppressed due to low confidence (1)
18/umbraco-cms/extend-your-project/backoffice-extensions/foundation/localization.md:114
- This sentence exceeds the documentation style guide’s 25-word guideline and is doing multiple jobs (prerequisite + how to extend types + analogy). Splitting it into shorter sentences will improve scanability (e.g., first sentence about prerequisite registration, second about augmenting
UmbKnownLocalizationSet, third about theUmbExtensionManifestMappattern).
Once you have [registered your localization extension](#registering-localization), you can teach the type system about your own keys by extending the global `UmbKnownLocalizationSet` interface from anywhere in your code (same pattern as `UmbExtensionManifestMap`):
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Available from Umbraco 18.1. | ||
| {% endhint %} | ||
|
|
||
| The `localize.term()` and `localize.termOrDefault()` methods, and the `key` attribute on `<umb-localize>`, are typed against the canonical English dictionary that ships with the backoffice. Editors that support TypeScript (VS Code, WebStorm, Rider) autocomplete every known key as you type, and function-valued entries forward their parameter list so calls are checked at compile time: |
📋 Description
Adds a new Type-safe localization keys section to
18/umbraco-cms/extend-your-project/backoffice-extensions/foundation/localization.md, documenting the compile-time validation that ships in Umbraco 18.1 via umbraco/Umbraco-CMS#22887.The new section covers:
localize.term(),termOrDefault(), and the<umb-localize key=\"…\">element now autocomplete every canonical key and check function-entry arguments at compile time.declare global { interface UmbKnownLocalizationSet { … } }), same pattern asUmbExtensionManifestMap.Lives between Using the Localizations and Using arguments in the existing article — the natural flow goes: register → use → type-safety story → arg/placeholder details.
v17 docs are intentionally left unchanged. The feature is v18.1+.
📎 Related Issues (if applicable)
Documents umbraco/Umbraco-CMS#22887.
✅ Contributor Checklist
I've followed the Umbraco Documentation Style Guide and can confirm that:
Product & Version (if relevant)
Umbraco CMS v18.1.
Deadline (if relevant)
Ideally lands alongside the v18.1 release so the docs and the feature ship together.