Localization

Learn how to manage and use the Backoffice UI Localization files.

Registering Localization

When registering 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.

The umbraco-package.json file is only registered when placed directly in the /App_Plugins/ or /App_Plugins/{YourPackageName} folder. It will not be recognized in nested subfolders.

Usually, the localization keys are provided through a JavaScript module. In this example, we will use a file named en.js:

umbraco-package.json

{
  "name": "MyPackage",
  "extensions": [
    {
      "type": "localization",
      "alias": "MyPackage.Localize.EnUS",
      "name": "English",
      "meta": {
        "culture": "en"
      },
      "js": "/App_Plugins/MyPackage/Localization/en.js"
    }
  ]
}

Read more about extensions in the Package Manifest article.

The Localization file

The localization files for the UI are JavaScript modules with a default export containing a key-value structure organized in sections.

en.js

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.

If you do not have many translations, you can also choose to include them directly in the meta-object using the localizations property:

umbraco-package.json

{
  "name": "MyPackage",
  "extensions": [
    {
      "type": "localization",
      "alias": "MyPackage.Localize.EnUS",
      "name": "English",
      "meta": {
        "culture": "en",
        "localizations": {
          "section": {
            "key1": "value1",
            "key2": "value2"
          }
        }
      },
    }
  ]
}

All keys must be wrapped within a single grouping level (for example section) inside the localizations object. You cannot place key-value pairs directly under localizations, and further nesting is not supported.

In this case, the en.js file is not required and we can remove the "js" property from the manifest. Only strings can be used in the meta-object.