Skip to content

'Defining Content > Document Type Localization' V16 update #7343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

'Defining Content > Document Type Localization' V16 update #7343

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f514794
Updates to doctype localization v16
Lili-Rossiter Aug 26, 2025
d6d7023
doctype-en.js
Lili-Rossiter Aug 26, 2025
5513a66
remove comment from json code sample as it is invalid
Lili-Rossiter Aug 26, 2025
e0ae57f
updated two step process to three steps
Lili-Rossiter Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 41 additions & 18 deletions 16/umbraco-cms/fundamentals/data/defining-content/document-type-localization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
---
description: Here you will learn how to apply localization for Document Types in Umbraco.
description: Setup localization for Document Types in the Umbraco backoffice.
---

# Document Type Localization

{% hint style="warning" %}
This article is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.
{% endhint %}

The Umbraco backoffice is localized to match the [user's configured language](../users/README.md).
The Umbraco backoffice is localized to match the [user's configured UI Culture](../../../tutorials/multilanguage-setup#changing-the-default-backoffice-language-of-a-user).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strangely enough, the link is displayed as an external link and gives a 404 when you click on it, while the one below on line 17 is OK. The only difference I could spot is the missing .md extension at the end of the main file name, could that be it?

Cf. screenshot: the url links to githuib instead of umbraco docs

image


When defining a Document Type, you can apply localization to:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a global suggestion for the last 3 bullet points below: we have a strange mix of singular and plural IMHO. I would either leave the element singular and then what follows also singular, either all plural.

So for example, for the second bullet:
Property name and description or Properties names and descriptions

I hope this makes sense ? 😅


Expand All @@ -17,18 +13,45 @@
* Custom property validation messages.
* Tab and group names.

Setting up localization for Document Types is a two-step process:

* Create the localizations in [user defined backoffice localization file](../../../customizing/foundation/localization.md).
Setting up localization for Document Types is a three-step process:
* Register the Document Type localization Files via [a new manifest 'umbraco-package.json' file](../../../customizing/extending-overview/extension-types/localization.md#registering-localization).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would write the word Files without capital letters.

* Create the localizations in [user defined Document Type localization files](../../../customizing/extending-overview/extension-types/localization.md#the-localization-file).
* Apply the localizations to the Document Type.

{% hint style="info" %}
Everything in this article also applies to defining [Media Types](../creating-media/) and Member Types.
Everything in this article also applies to defining [Media Types](../../backoffice#media-types) and [Member Types](../../backoffice#member-types).
{% endhint %}

## Registering Document Type localization Files

To register Document Type localizations, you must create a new manifest using an `umbraco-package.json` file.

Check warning on line 27 in 16/umbraco-cms/fundamentals/data/defining-content/document-type-localization.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[UmbracoDocs.UmbracoTerms] We prefer 'Umbraco' over 'umbraco.'

Raw Output:
{"message": "[UmbracoDocs.UmbracoTerms] We prefer 'Umbraco' over 'umbraco.'", "location": {"path": "16/umbraco-cms/fundamentals/data/defining-content/document-type-localization.md", "range": {"start": {"line": 27, "column": 83}}}, "severity": "WARNING"}

{% hint style="info" %}
The `umbraco-package.json` file is only registered when placed directly in the `/App_Plugins/` or `/App_Plugins/{SubFolderName}` folder. It will not be recognized in nested subfolders.
{% endhint %}

{% code title="umbraco-package.json" %}

Check warning on line 33 in 16/umbraco-cms/fundamentals/data/defining-content/document-type-localization.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[UmbracoDocs.UmbracoTerms] We prefer 'Umbraco' over 'umbraco.'

Raw Output:
{"message": "[UmbracoDocs.UmbracoTerms] We prefer 'Umbraco' over 'umbraco.'", "location": {"path": "16/umbraco-cms/fundamentals/data/defining-content/document-type-localization.md", "range": {"start": {"line": 33, "column": 16}}}, "severity": "WARNING"}
```json
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not very clear to me if there are parts in the manifest where I have to use the actual alias of the associated document type, or if I need to use specifically the generic term DocumentType.

For example, if I am localizing my custom document type named MikeDocumentType, what do I have to specifiy as alias: DocumentType.Localize.En as written currently, or MikeDocumentType.Localize.En ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I just opened the linked docs mentioned above 😅 and it seems to be indeed the actual document type name that needs to be used. I would suggest to then maybe reflect it in the sample for more direct clarity?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mikecp Localization works with keys like in the 'old' backoffice. There is no connection to your content type and the registration of the language file. The alias needs to be unique, that's it.

{
"name": "Document Type Localization",
"extensions": [
{
"type": "localization",
"alias": "DocumentType.Localize.En",
"name": "English",
"meta": {
"culture": "en"
},
"js": "/App_Plugins/DocumentTypeLocalization/doctype-en.js"
}
]
}
```
{% endcode %}

## Creating localizations

Once you have [registered a backoffice localization file](../../../customizing/extending-overview/extension-types/localization.md), you can add your localization texts for use in Document Types. The following localizations are used for the samples in this article:
Once you have registered the Document Type localization, you can add your localization texts for use in Document Types. The following localizations are used for the samples in this article:

{% code title="doctype-en.js" lineNumbers="true" %}
```js
Expand Down Expand Up @@ -65,16 +88,16 @@

The localizations are applied by using the syntax `#{area alias}_{key alias}`.

1. Create a **Document Type with template** called `#contentTypes_article` with **alias**: `articlePage`.
1. Create a **Document Type with Template** called `#contentTypes_article` with the **alias**: `articlePage`.
2. Under the newly created Document Type follow these steps:

* Name the **description** to `#contentTypes_article-desc`.
* Set the **description** to `#contentTypes_article-desc`.
* Create a new **tab** called `#tabs_content`.
* Add a new **group** called `#groups_titles`.
* Add a **property** called `#properties_title` with **alias** `title`.
* Set description to `{#properties_title-desc}`.
* Set the description to `{#properties_title-desc}`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just making sure that it is normal that it's the only place where we use {} around the #area_key part.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mikecp it is. The descriptions support Umbraco Flavoured markdown, so that's why the { } are needed.

* Use a `TextString` editor.
* Enable to `Set this field as mandatory`.
* Set the field validation to `mandatory`.
* Under validation add `#properties_title-message`.

{% hint style="info" %}
Expand All @@ -84,7 +107,7 @@
![Applying localization to a property](../images/localization-document-type-editor-validation-v15.png)

* Add a **property** called `#properties_subTitle` with **alias** `subTitle`.
* Set description to `{#properties_subTitle-desc}`.
* Set the description to `{#properties_subTitle-desc}`.
* Use a `TextString` editor.
* Enable `Allow at root` in the **Structure** tab.

Expand All @@ -94,10 +117,10 @@

![Localized document creation dialog](../images/localization-document-editor-create.png)

4. Create a new "Article" content:
4. Create a new "Article" node:

![Localized document editing](../images/localization-document-editor-v15.png)

4. When trying to save the content without adding the mandatory content, you will see a warning as expected:
5. When trying to save the node without adding the mandatory content, you will see a warning as expected:

![Localized property validation](../images/localization-document-editor-validation.png)
Loading