Back to Details

umbraco-localization

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Umbraco Localization

Umbraco 本地化

What is it?

什么是本地化？

Localization enables UI translation through localization files managed by the Extension Registry, with English (iso code: 'en') as the fallback language. The Localization Controller (automatically available in Umbraco Elements via 
this.localize
) provides access to translated strings using keys. Custom translations can be added via the Extension Registry and referenced in manifests using the 
#
prefix.
本地化功能可通过Extension Registry管理的本地化文件实现UI翻译，默认回退语言为英语（ISO代码：'en'）。Localization Controller（可通过
this.localize
在Umbraco Elements中自动获取）允许通过键值访问已翻译的字符串。你可以通过Extension Registry添加自定义翻译，并在清单中使用
#
前缀引用这些翻译。

Documentation

文档

Always fetch the latest docs before implementing:
在实现前请务必获取最新文档：

Workflow

工作流程

  1. Fetch docs - Use WebFetch on the URLs above
  2. Ask questions - Using built-in keys or custom? Need pluralization? Dynamic values?
  3. Generate code - Implement localization based on latest docs
  4. Explain - Show what was created and how to test
  1. 获取文档 - 使用WebFetch访问上述URL
  2. 提出问题 - 使用内置键还是自定义键？需要复数处理吗？需要动态值吗？
  3. 生成代码 - 根据最新文档实现本地化
  4. 解释说明 - 展示创建的内容以及测试方法

Minimal Examples

极简示例

Using Localize Controller (Umbraco Element)

使用Localize Controller（Umbraco元素）

typescript
import { html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-element')
export class MyElement extends UmbLitElement {
  render() {
    return html`
      <uui-button .label=${this.localize.term('general_close')}>
        ${this.localize.term('general_close')}
      </uui-button>
      <p>${this.localize.term('general_welcome')}</p>
    `;
  }
}
typescript
import { html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-element')
export class MyElement extends UmbLitElement {
  render() {
    return html`
      <uui-button .label=${this.localize.term('general_close')}>
        ${this.localize.term('general_close')}
      </uui-button>
      <p>${this.localize.term('general_welcome')}</p>
    `;
  }
}

Using Localize Controller with fallback (Umbraco 17.1+ only!)

使用带回退功能的Localize Controller（仅Umbraco 17.1+支持！）

typescript
import { html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-element')
export class MyElement extends UmbLitElement {
  render() {
    return html`
      <p>Renders "Welcome": ${this.localize.term('general_welcome')}</p>
      <p>Renders "This is a fallback": ${this.localize.termOrDefault('test_unavailable', 'This is a fallback')}</p>
    `;
  }
}
typescript
import { html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-element')
export class MyElement extends UmbLitElement {
  render() {
    return html`
      <p>Renders "Welcome": ${this.localize.term('general_welcome')}</p>
      <p>Renders "This is a fallback": ${this.localize.termOrDefault('test_unavailable', 'This is a fallback')}</p>
    `;
  }
}

Using Localize Element

使用Localize元素

typescript
render() {
  return html`
    <button>
      <umb-localize key="dialog_myKey">Default Text</umb-localize>
    </button>
  `;
}
typescript
render() {
  return html`
    <button>
      <umb-localize key="dialog_myKey">Default Text</umb-localize>
    </button>
  `;
}

Manual Localize Controller

手动实例化Localize Controller

typescript
import { UmbLocalizationController } from '@umbraco-cms/backoffice/localization-api';
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';

export class MyController extends UmbControllerBase {
  #localize = new UmbLocalizationController(this);

  render() {
    return html`
      <uui-button .label=${this.#localize.term('general_close')}>
      </uui-button>
    `;
  }
}
typescript
import { UmbLocalizationController } from '@umbraco-cms/backoffice/localization-api';
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';

export class MyController extends UmbControllerBase {
  #localize = new UmbLocalizationController(this);

  render() {
    return html`
      <uui-button .label=${this.#localize.term('general_close')}>
      </uui-button>
    `;
  }
}

Custom Localization File

自定义本地化文件

javascript
// en.js
export default {
  myExtension: {
    welcomeMessage: 'Welcome to my extension!',
    itemCount: 'You have {0} items',
    goodbye: 'Goodbye, {0}!',
  },
};
javascript
// en.js
export default {
  myExtension: {
    welcomeMessage: 'Welcome to my extension!',
    itemCount: 'You have {0} items',
    goodbye: 'Goodbye, {0}!',
  },
};

Registering Custom Localizations

注册自定义本地化

typescript
// manifest.ts
export const manifests = [
  {
    type: 'localization',
    alias: 'My.Localization.En',
    name: 'English Localization',
    meta: {
      culture: 'en',
    },
    js: () => import('./localization/en.js'),
  },
];
typescript
// manifest.ts
export const manifests = [
  {
    type: 'localization',
    alias: 'My.Localization.En',
    name: 'English Localization',
    meta: {
      culture: 'en',
    },
    js: () => import('./localization/en.js'),
  },
];

Using Custom Keys

使用自定义键

typescript
render() {
  return html`
    <h1>${this.localize.term('myExtension_welcomeMessage')}</h1>
    <p>${this.localize.term('myExtension_itemCount', 5)}</p>
  `;
}
typescript
render() {
  return html`
    <h1>${this.localize.term('myExtension_welcomeMessage')}</h1>
    <p>${this.localize.term('myExtension_itemCount', 5)}</p>
  `;
}

Localization with Arguments

带参数的本地化

javascript
// Localization file with function
export default {
  section: {
    numberOfItems: (count) => {
      if (count === 0) return 'Showing nothing';
      if (count === 1) return 'Showing only one item';
      return `Showing ${count} items`;
    },
  },
};
typescript
// Usage
render() {
  return html`
    <umb-localize
      key="section_numberOfItems"
      .args=${[this._itemCount]}
    ></umb-localize>
  `;
}
javascript
// 包含函数的本地化文件
export default {
  section: {
    numberOfItems: (count) => {
      if (count === 0) return 'Showing nothing';
      if (count === 1) return 'Showing only one item';
      return `Showing ${count} items`;
    },
  },
};
typescript
// 使用示例
render() {
  return html`
    <umb-localize
      key="section_numberOfItems"
      .args=${[this._itemCount]}
    ></umb-localize>
  `;
}

Localize in Manifest

在清单中使用本地化

json
{
  "type": "dashboard",
  "alias": "My.Dashboard",
  "name": "My Dashboard",
  "meta": {
    "label": "#welcomeDashboard_label",
    "pathname": "welcome"
  }
}
json
{
  "type": "dashboard",
  "alias": "My.Dashboard",
  "name": "My Dashboard",
  "meta": {
    "label": "#welcomeDashboard_label",
    "pathname": "welcome"
  }
}

Common Built-in Keys

常用内置键

typescript
// General
this.localize.term('general_close')
this.localize.term('general_cancel')
this.localize.term('general_save')
this.localize.term('general_delete')
this.localize.term('general_welcome')

// Actions
this.localize.term('actions_create')
this.localize.term('actions_edit')
this.localize.term('actions_remove')

// Dialogs
this.localize.term('dialog_confirm')
this.localize.term('dialog_cancel')
typescript
// 通用
this.localize.term('general_close')
this.localize.term('general_cancel')
this.localize.term('general_save')
this.localize.term('general_delete')
this.localize.term('general_welcome')

// 操作
this.localize.term('actions_create')
this.localize.term('actions_edit')
this.localize.term('actions_remove')

// 对话框
this.localize.term('dialog_confirm')
this.localize.term('dialog_cancel')

Debug Mode

调试模式

html
<!-- Shows the key alias instead of value for troubleshooting -->
<umb-localize key="myExtension_welcomeMessage" debug="true"></umb-localize>
html
<!-- 显示键别名而非对应值，用于故障排查 -->
<umb-localize key="myExtension_welcomeMessage" debug="true"></umb-localize>

Multiple Languages

多语言支持

typescript
// en.js
export default {
  greeting: 'Hello',
};

// da.js (Danish)
export default {
  greeting: 'Hej',
};

// Register both
export const manifests = [
  {
    type: 'localization',
    alias: 'My.Localization.En',
    meta: { culture: 'en' },
    js: () => import('./localization/en.js'),
  },
  {
    type: 'localization',
    alias: 'My.Localization.Da',
    meta: { culture: 'da' },
    js: () => import('./localization/da.js'),
  },
];
typescript
// en.js
export default {
  greeting: 'Hello',
};

// da.js（丹麦语）
export default {
  greeting: 'Hej',
};

// 注册两种语言
export const manifests = [
  {
    type: 'localization',
    alias: 'My.Localization.En',
    meta: { culture: 'en' },
    js: () => import('./localization/en.js'),
  },
  {
    type: 'localization',
    alias: 'My.Localization.Da',
    meta: { culture: 'da' },
    js: () => import('./localization/da.js'),
  },
];

Key Concepts

核心概念

Localize Controller: Auto-available in Umbraco Elements via 
this.localize
Translation Keys: Use underscore notation (e.g., 
general_close
, 
myExtension_welcomeMessage
)
Fallback: English (en) is the default fallback when translations are missing - all extensions should, as a minimum, include an 'en' localization manifest
Default text: If unsure whether the localization key exists, or for easier readability, add a default text to 
<umb-localize key="section_key">Default text</umb-localize>
or as second argument to 
termOrDefault()
Arguments: Pass dynamic values using 
.args
attribute or second parameter to 
term()
Manifest Localization: Prefix values with 
#
to reference translation keys
Debug Mode: Use 
debug="true"
to show key aliases for troubleshooting
File Structure:
  • One file per language (en.js, da.js, etc.)
  • Export default object with nested keys
  • Register via Extension Registry
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.
Localize Controller：可通过
this.localize
在Umbraco Elements中自动获取
翻译键：使用下划线命名法（例如：
general_close
、
myExtension_welcomeMessage
）
回退机制：当翻译缺失时，默认回退到英语（en）——所有扩展至少应包含一个'en'本地化清单
默认文本：若不确定本地化键是否存在，或为了提高可读性，可在
<umb-localize key="section_key">Default text</umb-localize>
中添加默认文本，或作为
termOrDefault()
的第二个参数
参数传递：使用
.args
属性或
term()
的第二个参数传递动态值
清单本地化：在值前添加
#
前缀以引用翻译键
调试模式：使用
debug="true"
显示键别名以进行故障排查
文件结构：
  • 每种语言对应一个文件（en.js、da.js等）
  • 导出默认对象，包含嵌套键
  • 通过Extension Registry注册
就是这样！请务必获取最新文档，保持示例简洁，生成完整可运行的代码。",