From 0ae47f6285e88d1dcd39d3c4cf0d2a8f5d71892d Mon Sep 17 00:00:00 2001 From: kjac Date: Mon, 10 Jun 2024 14:31:39 +0200 Subject: [PATCH 1/3] Update language/localization docs --- .../extending/language-files/README.md | 23 ++++------- .../language-files/net-localization.md | 38 ++++++++++++------- 2 files changed, 32 insertions(+), 29 deletions(-) diff --git a/14/umbraco-cms/extending/language-files/README.md b/14/umbraco-cms/extending/language-files/README.md index 51d43bcdcba..5d903f865af 100644 --- a/14/umbraco-cms/extending/language-files/README.md +++ b/14/umbraco-cms/extending/language-files/README.md @@ -1,32 +1,25 @@ --- description: >- This article overviews how an Umbraco CMS website uses and manages - localization files. + localization with language files. --- # Language Files & Localization -{% hint style="warning" %} -The Language Files & Localization articles are a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} +Language files are used to localise the Umbraco backoffice, so Users can use Umbraco in their native language. This is particularly important for content editors who do not speak English. -Localization files are used to translate: +With language files, you can also: -* The Umbraco backoffice user interface so that end users can use Umbraco in their native language. This is particularly important for content editors who do not speak English. -* The member identity errors in an Umbraco website enable end users to use Umbraco in the website language. +* Override existing (core) localizations. +* Define localization for your own package. -You can also: +## [UI Localization](ui-localization.md) -* Override existing language files. -* Include translations for your own package. Read [Add translations for your packages](../../extending/packages/language-files-for-packages.md) to see how to you can achieve this. +Defines how to use the UI Umbraco Localization. This is the primary source of localization for the backoffice. ## [.NET Localization](net-localization.md) -Defines how to use the .NET Core Umbraco Localization files. - -## [UI Localization](ui-localization.md) - -Defines how to use the UI Umbraco Localization files. +Defines how to use the .NET Core Umbraco Localization. This is only relevant for localization that happens server-side - for example, for sending emails. {% hint style="info" %} You can use localization files for Document and Media Types as well. You can find more information about this in the [Document Type Localization](../../fundamentals/data/defining-content/document-type-localization.md) article. diff --git a/14/umbraco-cms/extending/language-files/net-localization.md b/14/umbraco-cms/extending/language-files/net-localization.md index 3345ffe0756..fb8fc7f33b1 100644 --- a/14/umbraco-cms/extending/language-files/net-localization.md +++ b/14/umbraco-cms/extending/language-files/net-localization.md @@ -4,14 +4,20 @@ description: NET Umbraco Core Localization files. # .NET Localization -{% hint style="warning" %} -This page is a work in progress. It will be updated as the software evolves. -{% endhint %} - ## .NET Localization In this article, you will find information about the Core Localization files. You can also find information about where to find and use them, and how to keep them up-to-date. +### Use cases + +.NET localization has very limited use cases in Umbraco, as all backoffice localization is performed with [UI Localization](ui-localization.md). + +In other words, .NET localization is only applied server-side with no accompanying UI - for example: + +- Sending emails. +- User login error handling. +- Health checks. + ### Where to find the core localization files The core Umbraco localization files are found at the following location within the [Umbraco source](https://github.com/umbraco/Umbraco-CMS/tree/contrib/src/Umbraco.Core/EmbeddedResources/Lang): @@ -24,7 +30,7 @@ These localization files are shipped with Umbraco and should not be modified. #### User localization files -If you want to override Umbraco Core translations or translations shipped with packages, these files are located here: +If you want to override Umbraco Core .NET localization, create new files in this location and format: ```xml /config/lang/{language}.user.xml @@ -34,8 +40,6 @@ If you want to override Umbraco Core translations or translations shipped with p The `/config/lang/` folders do not exist on a clean installation of the CMS. You will need to create them at the root of your project. In an Umbraco Cloud project this will need to be in the `src` project. {% endhint %} -By default, these files are empty but you can add any new keys you want or override existing ones with your own translations. The nice part about the user files is that they will not get overwritten by the installer when you upgrade your Umbraco versions. - In order for these files to deploy when you do a `dotnet publish`, you need to add the following to your `.csproj` file: ```xml @@ -46,18 +50,24 @@ In order for these files to deploy when you do a `dotnet publish`, you need to a ### Using the localizations -`ILocalizedTextService` is used to localize strings, and is available through dependency injection. First, inject the service, and then use the `Localize()` method available in the namespace `Umbraco.Extensions` to localize the string with the format `[area]/[key]`: +`ILocalizedTextService` is used to localize strings, and is available through dependency injection. You can use the `Localize()` method available in the namespace `Umbraco.Extensions` to localize the string by `area` and `key`: ```csharp -public MyClass(ILocalizedTextService textservice) +using Umbraco.Cms.Core.Services; + +namespace UmbracoDocs.Samples; + +public class LocalizationSample { - var localizedLabel = textservice.Localize("dialog/mykey"); -} -``` + private readonly ILocalizedTextService _localizedTextService; -#### Package localization files + public LocalizationSample(ILocalizedTextService localizedTextService) + => _localizedTextService = localizedTextService; -If you are a package developer, see the article for [UI Localization](broken-reference). + public string LocalizeMyText(string area, string key) + => _localizedTextService.Localize(area, key); +} +``` ### Help keep the language files up to date From 4631f36287b6103fb59be4b460b402481d43274c Mon Sep 17 00:00:00 2001 From: kjac Date: Mon, 10 Jun 2024 14:36:43 +0200 Subject: [PATCH 2/3] Make the linter happy --- 14/umbraco-cms/extending/language-files/net-localization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-cms/extending/language-files/net-localization.md b/14/umbraco-cms/extending/language-files/net-localization.md index fb8fc7f33b1..60c747507cc 100644 --- a/14/umbraco-cms/extending/language-files/net-localization.md +++ b/14/umbraco-cms/extending/language-files/net-localization.md @@ -10,7 +10,7 @@ In this article, you will find information about the Core Localization files. Yo ### Use cases -.NET localization has very limited use cases in Umbraco, as all backoffice localization is performed with [UI Localization](ui-localization.md). +.NET localization has limited use cases in Umbraco, as all backoffice localization is performed with [UI Localization](ui-localization.md). In other words, .NET localization is only applied server-side with no accompanying UI - for example: From 9798ec8ede8fda8290f31fc0c7a5b501bd8fcb66 Mon Sep 17 00:00:00 2001 From: jonat123 <54025331+jonat123@users.noreply.github.com> Date: Mon, 17 Jun 2024 10:27:46 +0200 Subject: [PATCH 3/3] Update 14/umbraco-cms/extending/language-files/net-localization.md --- 14/umbraco-cms/extending/language-files/net-localization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-cms/extending/language-files/net-localization.md b/14/umbraco-cms/extending/language-files/net-localization.md index 60c747507cc..e6f3676b4ab 100644 --- a/14/umbraco-cms/extending/language-files/net-localization.md +++ b/14/umbraco-cms/extending/language-files/net-localization.md @@ -30,7 +30,7 @@ These localization files are shipped with Umbraco and should not be modified. #### User localization files -If you want to override Umbraco Core .NET localization, create new files in this location and format: +If you want to override Umbraco Core .NET localization, create new files in the following location and format: ```xml /config/lang/{language}.user.xml