From 62fe25fd1b64fde8039f4cd464c5fdc319ead250 Mon Sep 17 00:00:00 2001 From: "Alina-Magdalena Tincas (Umbraco HQ)" Date: Tue, 9 Apr 2024 11:34:51 +0200 Subject: [PATCH] restructure localization files for v14 --- .../localization/.net-localization.md | 6 - .../localization/README.md | 15 +- .../localization/net-localization.md | 10 +- .../extending-cms/language-files.md | 201 ------------------ 4 files changed, 19 insertions(+), 213 deletions(-) delete mode 100644 14/umbraco-cms/extending-backoffice/localization/.net-localization.md delete mode 100644 14/umbraco-cms/extending-cms/language-files.md diff --git a/14/umbraco-cms/extending-backoffice/localization/.net-localization.md b/14/umbraco-cms/extending-backoffice/localization/.net-localization.md deleted file mode 100644 index 31bc0aca641..00000000000 --- a/14/umbraco-cms/extending-backoffice/localization/.net-localization.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: NET Umbraco Core Localization files. ---- - -# .NET Localization - diff --git a/14/umbraco-cms/extending-backoffice/localization/README.md b/14/umbraco-cms/extending-backoffice/localization/README.md index d9e2fb664ab..c9527536155 100644 --- a/14/umbraco-cms/extending-backoffice/localization/README.md +++ b/14/umbraco-cms/extending-backoffice/localization/README.md @@ -11,15 +11,24 @@ Localization files are used to translate: * 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. -### [.NET Localization](net-localization.md) +You can also: + +* Override existing language files. +* Include translations for your own package. Read [Add translations for your packages](../../extending-cms/packages/language-files-for-packages.md) to see how to you can achieve this. + +## [.NET Localization](net-localization.md) Defines how to use the .NET Core Umbraco Localization files. -### [UI Localization](ui-localization.md) +## [UI Localization](ui-localization.md) Defines how to use the UI Umbraco Localization files. -## Supported Languages +{% 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. +{% endhint %} + +# Supported Languages Current [languages](https://github.com/umbraco/Umbraco-CMS/tree/contrib/src/Umbraco.Core/EmbeddedResources/Lang) with their ISO codes that are included in new Umbraco installations are: diff --git a/14/umbraco-cms/extending-backoffice/localization/net-localization.md b/14/umbraco-cms/extending-backoffice/localization/net-localization.md index 10885d8f59e..6cf24de75cd 100644 --- a/14/umbraco-cms/extending-backoffice/localization/net-localization.md +++ b/14/umbraco-cms/extending-backoffice/localization/net-localization.md @@ -28,6 +28,10 @@ If you want to override Umbraco Core translations or translations shipped with p /config/lang/{language}.user.xml ``` +{% hint style="info" %} +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. +{% 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: @@ -51,7 +55,7 @@ public MyClass(ILocalizedTextService textservice) ### Package localization files -If you are a package developer, see the article for[ UI Localization](ui-localization.md). +If you are a package developer, see the article for[UI Localization](ui-localization.md). ## Help keep the language files up to date @@ -70,7 +74,7 @@ The language files are XML files with a straight-forward layout as seen below. The Umbraco community - https://our.umbraco.com + https://community.umbraco.com Culture and Hostnames @@ -88,7 +92,7 @@ In the above example of a missing translation for "**assignDomain**", locate thi The Umbraco community - https://our.umbraco.com + https://community.umbraco.com Administrar hostnames diff --git a/14/umbraco-cms/extending-cms/language-files.md b/14/umbraco-cms/extending-cms/language-files.md deleted file mode 100644 index 54c44426218..00000000000 --- a/14/umbraco-cms/extending-cms/language-files.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -description: >- - This article overviews how language files are used and managed in a Umbraco - CMS website. ---- - -# Language Files & Localization - -Language files are XML files used to translate: - -* 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 enabling end users to use Umbraco in the website language. -* Read [Add translations for your packages](packages/language-files-for-packages.md) to see how to include translations for your own package. -* Override existing language files. - -{% 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. -{% endhint %} - -This is an example of such a language file, the most important parts are the `alias` fields of the `` and `` elements. This is what you need to retrieve the values from .NET or Angular. - -```xml - - - - The Umbraco community - https://community.umbraco.com - - - Culture and Hostnames - Audit Trail - - - Save - Cancel - - ... - -``` - -## Supported Languages - -Current languages that are included in new Umbraco installations are: - -* English (UK) -* English (US) -* Danish -* German -* Spanish -* French -* Hebrew (Israel) -* Italian -* Japanese -* Korean -* Dutch -* Norwegian -* Polish -* Portuguese -* Russian -* Swedish -* Chinese -* Chinese (Taiwan) -* Czech -* Turkish -* Welsh -* Ukrainian - -## Where to find the language files - -### Core language files - -The core Umbraco language files are found at the following location within the Umbraco source: - -```xml -Umbraco-CMS/src/Umbraco.Core/EmbeddedResources/Lang/ -``` - -These language files are the ones shipped with Umbraco and should not be modified. - -### Package language files - -If you are a package developer, [see here for docs on how to include translations for your own package](packages/language-files-for-packages.md), package language files are located in: - -```xml -/App_Plugins/mypackage/Lang/{language}.xml -``` - -{% hint style="info" %} -The `App_Plugins` version of the `Lang` directory is case sensitive on Linux systems, so make sure that it start with a capital `L`. -{% endhint %} - -### User language files - -If you want to override Umbraco core translations or translations shipped with packages, you can do that too, these files are located here: - -```xml -/config/lang/{language}.user.xml -``` - -{% hint style="info" %} -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 `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 - - - -``` - -## Using the language keys - -Using core or custom language keys from your code: - -### From .NET - -`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]`: - -```csharp -public MyClass(ILocalizedTextService textservice) -{ - var localizedLabel = textservice.Localize("dialog/mykey"); -} -``` - -### From Angular - -In the Umbraco backoffice UI, labels can be localized with the `localize` directive. The syntax is slightly different when compared to the .NET variant. Here the syntax is `\[area]_\[key]`: - -```xml - -``` - -The localize directive can also be used as an attribute like below where the value of the title attribute is then populated with the dictionary key "title\_name" from the language file using "@title\_name". - -```xml - -``` - -Or from a controller by using the `LocalizationService` which returns an async translation in a promise: - -```javascript -localizationService.localize("dialog_myKey").then(function(value){ - element.html(value); -}); -``` - -## Help keep the language files up to date - -As Umbraco is a continually evolving product it is inevitable that new text is added on a fairly regular basis to the English language version of these files. This may mean that some of the above languages are no longer up to date. - -If a translation is missing, the key "alias" used will be shown within the user interface, as an example: - -```xml -[assignDomain] -``` - -The language files are XML files with a straight-forward layout as seen below. - -```xml - - - - The Umbraco community - https://our.umbraco.com - - - Culture and Hostnames - Audit Trail - ... - - ... - -``` - -In the above example of a missing translation for "assignDomain", locate this string in the en.xml file and then copy the whole "Key" element into the relevant language file. Then you can translate the text, as an example here is the Spanish version of the above snippet: - -```xml - - - - The Umbraco community - https://our.umbraco.com - - - Administrar hostnames - Auditoría - ... - - ... - -``` - -If you do update any of the core language files or you add a new language, don't forget to help the rest of the community by [submitting a pull request](https://docs.umbraco.com/welcome/contribute/getting-started) so that your changes are merged into the core.