umbraco-localization

Umbraco ローカライズ

これは何ですか？

ローカライズは、Extension Registry によって管理されるローカライズファイルを通じて UI の翻訳を可能にし、英語（ISO コード: 'en'）がフォールバック言語となります。Localization Controller（Umbraco Elements で this.localize を通じて自動的に利用可能）は、キーを使用して翻訳された文字列へのアクセスを提供します。カスタム翻訳は 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. 説明 - 作成した内容とテスト方法を示します

最小限の例

Localize Controller の使用（Umbraco Element）

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

フォールバック付き Localize Controller の使用（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>
    `;
  }
}

Localize Element の使用

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

手動 Localize Controller

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

主要な概念

Localize Controller: Umbraco Elements で this.localize を通じて自動的に利用可能

翻訳キー: アンダースコア記法を使用します（例: general_close、myExtension_welcomeMessage）

フォールバック: 翻訳が存在しない場合、英語（en）がデフォルトのフォールバックです - すべての拡張機能は、最低限 'en' ローカライズマニフェストを含める必要があります

デフォルトテキスト: ローカライズキーが存在するか不明な場合、または可読性を高めるために、<umb-localize key="section_key">Default text</umb-localize> にデフォルトテキストを追加するか、termOrDefault() の第 2 引数として追加します

引数: .args 属性または term() の第 2 パラメーターを使用して動的な値を渡します

マニフェストのローカライズ: 翻訳キーを参照するには、値の先頭に # を付けます

デバッグモード: トラブルシューティングのためにキーエイリアスを表示するには debug="true" を使用します

ファイル構造:

• 言語ごとに 1 ファイル（en.js、da.js など）
• ネストされたキーを持つデフォルトオブジェクトをエクスポート
• Extension Registry を通じて登録

以上です！常に最新のドキュメントを取得し、例を最小限に保ち、完全に動作するコードを生成してください。