From eec9371477de930a4de2bf52697b9b4afd4b6722 Mon Sep 17 00:00:00 2001 From: Jonathan Date: Tue, 25 Jun 2024 13:02:20 +0200 Subject: [PATCH 01/11] Updated articles based on feedback from DXP team --- 14/umbraco-cms/extending/packages/README.md | 2 +- .../installing-and-uninstalling-packages.md | 2 +- .../packages/language-files-for-packages.md | 81 ++++++++++++------- 3 files changed, 52 insertions(+), 33 deletions(-) diff --git a/14/umbraco-cms/extending/packages/README.md b/14/umbraco-cms/extending/packages/README.md index 11124caa71b..c467c625216 100644 --- a/14/umbraco-cms/extending/packages/README.md +++ b/14/umbraco-cms/extending/packages/README.md @@ -47,7 +47,7 @@ Content apps are almost like dashboards for content nodes that are intended to d #### Integration extensions -This type of package can be a lot of things, and can include a number of the other package types. They are generally integrating a larger system into Umbraco. A good example could be an e-commerce package such as [UCommerce](https://marketplace.umbraco.com/package/ucommerce.umbraco8), that includes an entire webshop module for Umbraco. +This type of package can be a lot of things, and can include a number of the other package types. They are generally integrating a larger system into Umbraco. A good example could be an e-commerce package such as [Umbraco Commerce](https://docs.umbraco.com/umbraco-commerce), that includes an entire webshop module for Umbraco. ## [Types of Packages](types-of-packages.md) diff --git a/14/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md b/14/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md index f24d1d42889..f438567441e 100644 --- a/14/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md +++ b/14/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md @@ -22,7 +22,7 @@ In the Umbraco Backoffice, you will find a **Packages** section that displays th ![Backoffice - Packages section](images/backoffice-packages-section.png) {% hint style="warning" %} -For Umbraco CMS version 8 and earlier versions, the Packages section displays the [Packages site on Our](https://our.umbraco.com/packages/). +For Umbraco CMS version 8 and earlier, the Packages section displays the [Packages site on Our](https://our.umbraco.com/packages/). {% endhint %} {% tabs %} diff --git a/14/umbraco-cms/extending/packages/language-files-for-packages.md b/14/umbraco-cms/extending/packages/language-files-for-packages.md index fb2bc4ccd48..f510c21bd6d 100644 --- a/14/umbraco-cms/extending/packages/language-files-for-packages.md +++ b/14/umbraco-cms/extending/packages/language-files-for-packages.md @@ -2,39 +2,58 @@ description: "Information on how to use language files to make your Umbraco package UI support multiple languages" --- -# Language file for packages - -Umbraco Core includes language files, but package authors must provide their own for multi-lingual UI. - -## Including new language keys - -For each language your package supports, you include an .xml file in the same format as the core language files, named with its language code. The language files must be located in a `Lang` folder inside your package folder in `App_Plugins`. If your package assets are in `/App_Plugins/mypackage` all language files must be placed in the following locations: - -- English keys: `/App_Plugins/mypackage/Lang/en-US.xml` -- Danish keys: `/App_Plugins/mypackage/Lang/da-DK.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 %} +# Languages for packages + +If you want your package to be available in different languages, you can use the existing localizations from Umbraco or register your own localizations. The localizations are written as a key-value pair pattern. +To register localizations to a language, you must add a new manifest to the Extension API. The manifest can be added through the `umbraco-package.json` file like this: + +{% code title="umbraco-package.json" lineNumbers="true" %} + +```json +{ + ... + "name": "MyPackage", + "extensions": [ + { + "type": "localization", + "alias": "MyPackage.Localize.EnUS", + "name": "English (United States)", + "meta": { + "culture": "en-us" + }, + "js": "/App_Plugins/MyPackage/Localization/en-us.js" + } + ] +} +``` ## Language file format -Each language file can include one or more area. Each area contains a collection of language keys with the translation. - -For reference on the language file format see the core [language files on GitHub](https://github.com/umbraco/Umbraco-CMS/tree/v9/dev/src/Umbraco.Web.UI/umbraco/config/lang) +## Layout of the Localization Files -### Sample structure - -```xml - - - - The Umbraco community - http://mydomain.com - - - Min nøgle - Min anden nøgle - - +The localization files for the UI are JS modules with a default export containing a key-value structure organized in sections. +```Javascript +export default { + section: { + key1: 'value1', + key2: 'value2', + }, +}; +``` +The sections and keys will be formatted into a map in Umbraco with the format section_key1 and section_key2. These form the unique key they are requested. +The values can be either a string or a function that returns a string: + +```Javascript +export default { + section: { + key1: 'value1', + key2: (count) => { + count = parseInt(count, 10); + if (count === 0) return 'Nothing'; + if (count === 1) return 'One thing'; + return 'Many things'; + }, + }, +}; ``` +Read the [UI Localization documentation](../language-files/ui-localization.md) to learn more about using languages in Umbraco. \ No newline at end of file From 3b4adce7f572d91ed1a6253a1a26eb459f3e51c3 Mon Sep 17 00:00:00 2001 From: Jonathan Date: Wed, 26 Jun 2024 09:02:52 +0200 Subject: [PATCH 02/11] Removed rogue heading --- 14/umbraco-cms/extending/packages/language-files-for-packages.md | 1 - 1 file changed, 1 deletion(-) diff --git a/14/umbraco-cms/extending/packages/language-files-for-packages.md b/14/umbraco-cms/extending/packages/language-files-for-packages.md index f510c21bd6d..3303ad8f99e 100644 --- a/14/umbraco-cms/extending/packages/language-files-for-packages.md +++ b/14/umbraco-cms/extending/packages/language-files-for-packages.md @@ -27,7 +27,6 @@ To register localizations to a language, you must add a new manifest to the Exte } ``` -## Language file format ## Layout of the Localization Files From 4659b86be2f1560a3e8c50d28948ea73ff3d2cd9 Mon Sep 17 00:00:00 2001 From: Jonathan Date: Wed, 26 Jun 2024 09:17:41 +0200 Subject: [PATCH 03/11] removed mention of v8 in the article --- .../packages/installing-and-uninstalling-packages.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/14/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md b/14/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md index f438567441e..bcea06c4500 100644 --- a/14/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md +++ b/14/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md @@ -21,10 +21,6 @@ In the Umbraco Backoffice, you will find a **Packages** section that displays th ![Backoffice - Packages section](images/backoffice-packages-section.png) -{% hint style="warning" %} -For Umbraco CMS version 8 and earlier, the Packages section displays the [Packages site on Our](https://our.umbraco.com/packages/). -{% endhint %} - {% tabs %} {% tab title="NuGet package" %} Navigating to a specific package in the section will present you with an overview of the package, as well as an install snippet for NuGet CLI. From 053896fae9ebe0e8695110e45cfaca97b3915df0 Mon Sep 17 00:00:00 2001 From: jonat123 <54025331+jonat123@users.noreply.github.com> Date: Wed, 26 Jun 2024 09:22:06 +0200 Subject: [PATCH 04/11] Update 14/umbraco-cms/extending/packages/language-files-for-packages.md Co-authored-by: sofietoft --- .../extending/packages/language-files-for-packages.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/14/umbraco-cms/extending/packages/language-files-for-packages.md b/14/umbraco-cms/extending/packages/language-files-for-packages.md index 3303ad8f99e..29149be9b10 100644 --- a/14/umbraco-cms/extending/packages/language-files-for-packages.md +++ b/14/umbraco-cms/extending/packages/language-files-for-packages.md @@ -39,7 +39,8 @@ export default { }, }; ``` -The sections and keys will be formatted into a map in Umbraco with the format section_key1 and section_key2. These form the unique key they are requested. + +The sections and keys will be formatted into a map in Umbraco with the format `section_key1` and `section_key2`. These form the unique key that it requested. The values can be either a string or a function that returns a string: ```Javascript From 95afb5566a897cdb836f54b34bf717b868c18451 Mon Sep 17 00:00:00 2001 From: jonat123 <54025331+jonat123@users.noreply.github.com> Date: Wed, 26 Jun 2024 09:37:04 +0200 Subject: [PATCH 05/11] Update 14/umbraco-cms/extending/packages/language-files-for-packages.md Co-authored-by: sofietoft --- 14/umbraco-cms/extending/packages/language-files-for-packages.md | 1 + 1 file changed, 1 insertion(+) diff --git a/14/umbraco-cms/extending/packages/language-files-for-packages.md b/14/umbraco-cms/extending/packages/language-files-for-packages.md index 29149be9b10..57797b3a6da 100644 --- a/14/umbraco-cms/extending/packages/language-files-for-packages.md +++ b/14/umbraco-cms/extending/packages/language-files-for-packages.md @@ -31,6 +31,7 @@ To register localizations to a language, you must add a new manifest to the Exte ## Layout of the Localization Files The localization files for the UI are JS modules with a default export containing a key-value structure organized in sections. + ```Javascript export default { section: { From 5d55561a5328964963d0c36e9c00f7dcac4add0a Mon Sep 17 00:00:00 2001 From: Jonathan Date: Wed, 26 Jun 2024 09:56:53 +0200 Subject: [PATCH 06/11] Updated based on feedback from DXP team --- .../extending/packages/good-practice-and-defaults.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/14/umbraco-cms/extending/packages/good-practice-and-defaults.md b/14/umbraco-cms/extending/packages/good-practice-and-defaults.md index b7fb3071337..e3d382438b2 100644 --- a/14/umbraco-cms/extending/packages/good-practice-and-defaults.md +++ b/14/umbraco-cms/extending/packages/good-practice-and-defaults.md @@ -8,7 +8,9 @@ This document provides guides and notes on package development. It includes good ## Backoffice assets (JS/CSS/HTML) -To extend the Umbraco backoffice, a package can provide files such as a `package.manifest` and AngularJS views/controllers that should be stored within the `App_Plugins` folder. It's recommended to put all files in a subfolder with a unique name, preferably using the package name, like `App_Plugins\MyPackage`. +To extend the Umbraco backoffice, a package can provide files such as `umbraco-package.json` and typescript/javascript files that should be stored within the `App_Plugins` folder. It's recommended to put all files in a subfolder with a unique name, preferably using the package name, like `App_Plugins\MyPackage`. + +For more information on how to extend the Umbraco backoffice, have a look at the [customizing the backoffice documentation](../customize-backoffice/README.md) Files in the `App_Plugins` folder will be publicly available on the website even though they are not in the `wwwroot` folder. You should not store sensitive information in the `App_Plugins` folder. From 4a68f999fd4afb6d0b8347eaf993ca7aa16702b1 Mon Sep 17 00:00:00 2001 From: jonat123 <54025331+jonat123@users.noreply.github.com> Date: Wed, 26 Jun 2024 10:10:38 +0200 Subject: [PATCH 07/11] Update 14/umbraco-cms/extending/packages/good-practice-and-defaults.md --- 14/umbraco-cms/extending/packages/good-practice-and-defaults.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-cms/extending/packages/good-practice-and-defaults.md b/14/umbraco-cms/extending/packages/good-practice-and-defaults.md index e3d382438b2..d401368ba46 100644 --- a/14/umbraco-cms/extending/packages/good-practice-and-defaults.md +++ b/14/umbraco-cms/extending/packages/good-practice-and-defaults.md @@ -8,7 +8,7 @@ This document provides guides and notes on package development. It includes good ## Backoffice assets (JS/CSS/HTML) -To extend the Umbraco backoffice, a package can provide files such as `umbraco-package.json` and typescript/javascript files that should be stored within the `App_Plugins` folder. It's recommended to put all files in a subfolder with a unique name, preferably using the package name, like `App_Plugins\MyPackage`. +To extend the Umbraco backoffice, a package can provide files such as `umbraco-package.json` and Typescript/Javascript files that should be stored within the `App_Plugins` folder. It's recommended to put all files in a subfolder with a unique name, preferably using the package name, like `App_Plugins\MyPackage`. For more information on how to extend the Umbraco backoffice, have a look at the [customizing the backoffice documentation](../customize-backoffice/README.md) From 3a4aff0530e01d72763ae531596ebbcd0d5cd386 Mon Sep 17 00:00:00 2001 From: jonat123 <54025331+jonat123@users.noreply.github.com> Date: Wed, 26 Jun 2024 10:16:57 +0200 Subject: [PATCH 08/11] Update 14/umbraco-cms/extending/packages/good-practice-and-defaults.md --- 14/umbraco-cms/extending/packages/good-practice-and-defaults.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-cms/extending/packages/good-practice-and-defaults.md b/14/umbraco-cms/extending/packages/good-practice-and-defaults.md index d401368ba46..676905ce56c 100644 --- a/14/umbraco-cms/extending/packages/good-practice-and-defaults.md +++ b/14/umbraco-cms/extending/packages/good-practice-and-defaults.md @@ -8,7 +8,7 @@ This document provides guides and notes on package development. It includes good ## Backoffice assets (JS/CSS/HTML) -To extend the Umbraco backoffice, a package can provide files such as `umbraco-package.json` and Typescript/Javascript files that should be stored within the `App_Plugins` folder. It's recommended to put all files in a subfolder with a unique name, preferably using the package name, like `App_Plugins\MyPackage`. +To extend the Umbraco backoffice, a package can provide files such as `umbraco-package.json` and TypeScript/JavaScript files that should be stored within the `App_Plugins` folder. It's recommended to put all files in a subfolder with a unique name, preferably using the package name, like `App_Plugins\MyPackage`. For more information on how to extend the Umbraco backoffice, have a look at the [customizing the backoffice documentation](../customize-backoffice/README.md) From 1a84447295a462b3da34ab05a7c31b1ca93d880d Mon Sep 17 00:00:00 2001 From: Jonathan Date: Wed, 10 Jul 2024 10:19:12 +0200 Subject: [PATCH 09/11] Removed duplicate documentation --- .../packages/language-files-for-packages.md | 34 ++----------------- 1 file changed, 2 insertions(+), 32 deletions(-) diff --git a/14/umbraco-cms/extending/packages/language-files-for-packages.md b/14/umbraco-cms/extending/packages/language-files-for-packages.md index 57797b3a6da..5db40e513df 100644 --- a/14/umbraco-cms/extending/packages/language-files-for-packages.md +++ b/14/umbraco-cms/extending/packages/language-files-for-packages.md @@ -5,6 +5,7 @@ description: "Information on how to use language files to make your Umbraco pack # Languages for packages If you want your package to be available in different languages, you can use the existing localizations from Umbraco or register your own localizations. The localizations are written as a key-value pair pattern. + To register localizations to a language, you must add a new manifest to the Extension API. The manifest can be added through the `umbraco-package.json` file like this: {% code title="umbraco-package.json" lineNumbers="true" %} @@ -26,35 +27,4 @@ To register localizations to a language, you must add a new manifest to the Exte ] } ``` - - -## Layout of the Localization Files - -The localization files for the UI are JS modules with a default export containing a key-value structure organized in sections. - -```Javascript -export default { - section: { - key1: 'value1', - key2: 'value2', - }, -}; -``` - -The sections and keys will be formatted into a map in Umbraco with the format `section_key1` and `section_key2`. These form the unique key that it requested. -The values can be either a string or a function that returns a string: - -```Javascript -export default { - section: { - key1: 'value1', - key2: (count) => { - count = parseInt(count, 10); - if (count === 0) return 'Nothing'; - if (count === 1) return 'One thing'; - return 'Many things'; - }, - }, -}; -``` -Read the [UI Localization documentation](../language-files/ui-localization.md) to learn more about using languages in Umbraco. \ No newline at end of file +Read the [UI Localization documentation](../language-files/ui-localization.md) to learn in-depth on how you can use languages in your packages and Umbraco in general. \ No newline at end of file From 9ce80f751f414c0124a98e06ac57177183cbc10a Mon Sep 17 00:00:00 2001 From: Jonathan Date: Wed, 10 Jul 2024 10:23:09 +0200 Subject: [PATCH 10/11] removed mention of v8 and UCommerce --- 10/umbraco-cms/extending/packages/README.md | 2 +- .../packages/installing-and-uninstalling-packages.md | 3 --- 12/umbraco-cms/extending/packages/README.md | 2 +- .../packages/installing-and-uninstalling-packages.md | 4 ---- 13/umbraco-cms/extending/packages/README.md | 2 +- .../packages/installing-and-uninstalling-packages.md | 4 ---- 6 files changed, 3 insertions(+), 14 deletions(-) diff --git a/10/umbraco-cms/extending/packages/README.md b/10/umbraco-cms/extending/packages/README.md index 23635b0b765..392e6976644 100644 --- a/10/umbraco-cms/extending/packages/README.md +++ b/10/umbraco-cms/extending/packages/README.md @@ -30,7 +30,7 @@ Packages provide a wide variety of functionality, and can often span multiple ca #### Schema Extensions -A package that can be categorized as a Schema Extension will extend the default Umbraco Schema. Schema in this sense refers to things like Data Types, Property Editors, Document Types and Media Types. By extending Umbraco with packages such as [Our.Umbraco.GMaps](https://marketplace.umbraco.com/package/our.umbraco.gmaps) editors are given greater capabilities when they are populating their content pages. +A package that can be categorized as a Schema Extension will extend the default Umbraco Schema. Schema in this sense refers to things like Data Types, Property Editors, Document Types and Media Types. By extending Umbraco with packages such as [Umbraco Commerce](https://docs.umbraco.com/umbraco-commerce) editors are given greater capabilities when they are populating their content pages. #### Management Extensions diff --git a/10/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md b/10/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md index 1e4f8170ffa..545c5400257 100644 --- a/10/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md +++ b/10/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md @@ -21,9 +21,6 @@ In the Umbraco Backoffice, you will find a **Packages** section that displays th ![Backoffice - Packages section]() -{% hint style="warning" %} -For Umbraco CMS version 8 and earlier versions, the Packages section displays the [Packages site on Our](https://our.umbraco.com/packages/). -{% endhint %} {% tabs %} {% tab title="NuGet package" %} diff --git a/12/umbraco-cms/extending/packages/README.md b/12/umbraco-cms/extending/packages/README.md index 9a982b4c383..929f817fe52 100644 --- a/12/umbraco-cms/extending/packages/README.md +++ b/12/umbraco-cms/extending/packages/README.md @@ -44,7 +44,7 @@ Content apps are almost like dashboards for content nodes that are intended to d #### Integration extensions -This type of package can be a lot of things, and can include a number of the other package types. They are generally integrating a larger system into Umbraco. A good example could be an e-commerce package such as [UCommerce](https://marketplace.umbraco.com/package/ucommerce.umbraco8), that includes an entire webshop module for Umbraco. +This type of package can be a lot of things, and can include a number of the other package types. They are generally integrating a larger system into Umbraco. A good example could be an e-commerce package such as [Umbraco Commerce](https://docs.umbraco.com/umbraco-commerce), that includes an entire webshop module for Umbraco. ## [Types of Packages](types-of-packages.md) diff --git a/12/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md b/12/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md index f24d1d42889..bcea06c4500 100644 --- a/12/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md +++ b/12/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md @@ -21,10 +21,6 @@ In the Umbraco Backoffice, you will find a **Packages** section that displays th ![Backoffice - Packages section](images/backoffice-packages-section.png) -{% hint style="warning" %} -For Umbraco CMS version 8 and earlier versions, the Packages section displays the [Packages site on Our](https://our.umbraco.com/packages/). -{% endhint %} - {% tabs %} {% tab title="NuGet package" %} Navigating to a specific package in the section will present you with an overview of the package, as well as an install snippet for NuGet CLI. diff --git a/13/umbraco-cms/extending/packages/README.md b/13/umbraco-cms/extending/packages/README.md index 9a982b4c383..929f817fe52 100644 --- a/13/umbraco-cms/extending/packages/README.md +++ b/13/umbraco-cms/extending/packages/README.md @@ -44,7 +44,7 @@ Content apps are almost like dashboards for content nodes that are intended to d #### Integration extensions -This type of package can be a lot of things, and can include a number of the other package types. They are generally integrating a larger system into Umbraco. A good example could be an e-commerce package such as [UCommerce](https://marketplace.umbraco.com/package/ucommerce.umbraco8), that includes an entire webshop module for Umbraco. +This type of package can be a lot of things, and can include a number of the other package types. They are generally integrating a larger system into Umbraco. A good example could be an e-commerce package such as [Umbraco Commerce](https://docs.umbraco.com/umbraco-commerce), that includes an entire webshop module for Umbraco. ## [Types of Packages](types-of-packages.md) diff --git a/13/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md b/13/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md index f24d1d42889..bcea06c4500 100644 --- a/13/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md +++ b/13/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md @@ -21,10 +21,6 @@ In the Umbraco Backoffice, you will find a **Packages** section that displays th ![Backoffice - Packages section](images/backoffice-packages-section.png) -{% hint style="warning" %} -For Umbraco CMS version 8 and earlier versions, the Packages section displays the [Packages site on Our](https://our.umbraco.com/packages/). -{% endhint %} - {% tabs %} {% tab title="NuGet package" %} Navigating to a specific package in the section will present you with an overview of the package, as well as an install snippet for NuGet CLI. From 9586d9f043e7534ec40802036966c3702c2ac4d2 Mon Sep 17 00:00:00 2001 From: Jonathan Date: Wed, 10 Jul 2024 10:24:57 +0200 Subject: [PATCH 11/11] added mention of v8 packages back --- .../extending/packages/installing-and-uninstalling-packages.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/10/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md b/10/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md index 545c5400257..1e4f8170ffa 100644 --- a/10/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md +++ b/10/umbraco-cms/extending/packages/installing-and-uninstalling-packages.md @@ -21,6 +21,9 @@ In the Umbraco Backoffice, you will find a **Packages** section that displays th ![Backoffice - Packages section]() +{% hint style="warning" %} +For Umbraco CMS version 8 and earlier versions, the Packages section displays the [Packages site on Our](https://our.umbraco.com/packages/). +{% endhint %} {% tabs %} {% tab title="NuGet package" %}