umbraco-localization

Umbraco 本地化

这是什么？

本地化通过 Extension Registry 管理的本地化文件启用 UI 翻译，并以英语（ISO 代码：'en'）作为回退语言。本地化控制器（通过 this.localize 在 Umbraco 元素中自动提供）可使用键访问已翻译的字符串。可以通过 Extension Registry 添加自定义翻译，并在清单中使用 # 前缀引用。

文档

实施前务必获取最新文档：

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/localization
• Foundation：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• Extension Registry：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提问 - 使用内置键还是自定义键？需要复数形式吗？需要动态值吗？
3. 生成代码 - 根据最新文档实现本地化
4. 说明 - 展示创建的内容以及测试方法

最简示例

使用本地化控制器（Umbraco 元素）

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>
    `;
  }
}

使用带回退的本地化控制器（仅适用于 Umbraco 17.1+！）

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>
    `;
  }
}

使用本地化元素

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

手动使用本地化控制器

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>
    `;
  }
}

自定义本地化文件

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

注册自定义本地化内容

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

使用自定义键

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

带参数的本地化

// 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`;
    },
  },
};

// Usage
render() {
  return html`
    <umb-localize
      key="section_numberOfItems"
      .args=${[this._itemCount]}
    ></umb-localize>
  `;
}

在清单中本地化

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

常见内置键

// 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')

调试模式

<umb-localize key="myExtension_welcomeMessage" debug="true"></umb-localize>

多种语言

// 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'),
  },
];

核心概念

本地化控制器：通过 this.localize 在 Umbraco 元素中自动提供

翻译键：使用下划线表示法（例如，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 注册

就是这样！务必获取最新文档，保持示例简洁，并生成完整可运行的代码。