ランタイムローカライゼーションモード

Lit Localizeのランタイムモードでは、各ロケールに対して1つのJavaScriptまたはTypeScriptモジュールが生成されます。生成された各モジュールには、そのロケールのローカライズされたテンプレートが含まれています。アプリケーションでロケールを切り替えると、そのロケールのモジュールがインポートされ、すべてのローカライズされたコンポーネントが再レンダリングされます。

Lit Localizeの出力モードの比較については、出力モードを参照してください。

// locales/es-419.ts
export const templates = {
  h3c44aff2d5f5ef6b: html`Hola <b>Mundo!</b>`,
};

次の例は、Lit Localizeランタイムモードで構築されたアプリケーションを示しています。

LitのGitHubリポジトリには、完全な動作例（JavaScript、TypeScript）が含まれており、テンプレートとして使用できます。

lit-localize.jsonの設定ファイルで、output.modeプロパティをruntimeに設定し、output.outputDirプロパティをローカライズされたテンプレートモジュールを生成する場所に設定します。詳細については、ランタイムモードの設定を参照してください。

次に、output.localeCodesModuleを任意のファイルパスに設定します。Lit Localizeは、設定ファイルのsourceLocaleとtargetLocalesの設定をエクスポートされた変数として反映した.jsまたは.tsモジュールをここに生成します。生成されたモジュールは次のようになります。

export const sourceLocale = 'en';
export const targetLocales = ['es-419', 'zh-Hans'];
export const allLocales = ['en', 'es-419', 'zh-Hans'];

最後に、JavaScriptまたはTypeScriptプロジェクトで、次のプロパティを持つオブジェクトを渡してconfigureLocalizationを呼び出します。

• sourceLocale: string: 生成されたoutput.localeCodesModuleモジュールによってエクスポートされたsourceLocale変数。

• targetLocales: string[]: 生成されたoutput.localeCodesModuleモジュールによってエクスポートされたtargetLocales変数。

• loadLocale: (locale: string) => Promise<LocaleModule>: ローカライズされたテンプレートを読み込む関数。指定されたロケールコードの生成されたローカライズされたテンプレートモジュールを解決するPromiseを返します。ロケールモジュールの読み込み方法で、ここで使用できる関数の例を参照してください。

configureLocalizationは、次のプロパティを持つオブジェクトを返します。

• getLocale: アクティブなロケールコードを返す関数。新しいロケールの読み込みが開始された場合、getLocaleは新しいロケールが読み込みを完了するまで、以前のロケールコードを返し続けます。

• setLocale: アクティブなロケールを指定されたコードに切り替える処理を開始し、新しいロケールが読み込まれたときに解決されるPromiseを返す関数。使用例

例:

import {configureLocalization} from '@lit/localize';
// Generated via output.localeCodesModule
import {sourceLocale, targetLocales} from './generated/locale-codes.js';

export const {getLocale, setLocale} = configureLocalization({
  sourceLocale,
  targetLocales,
  loadLocale: (locale) => import(`/locales/${locale}.js`),
});

アクティブなロケールが切り替わるたびにコンポーネントの再レンダリングを自動的にトリガーするには、JavaScriptで記述する場合はコンストラクタでupdateWhenLocaleChanges関数を適用し、TypeScriptで記述する場合はクラスに@localizedデコレータを適用します。

import {LitElement, html} from 'lit';
import {customElement} from 'lit/decorators.js';
import {msg, localized} from '@lit/localize';

@customElement('my-element');
@localized()
class MyElement extends LitElement {
  render() {
    // Whenever setLocale() is called, and templates for that locale have
    // finished loading, this render() function will be re-invoked.
    return msg(html`Hello <b>World!</b>`);
  }
}

import {LitElement, html} from 'lit';
import {msg, updateWhenLocaleChanges} from '@lit/localize';

class MyElement extends LitElement {
  constructor() {
    super();
    updateWhenLocaleChanges(this);
  }

  render() {
    // Whenever setLocale() is called, and templates for that locale have
    // finished loading, this render() function will be re-invoked.
    return msg(html`Hello <b>World!</b>`);
  }
}
customElements.define('my-element', MyElement);

lit-localize-statusイベントは、ロケールの切り替えが開始、完了、または失敗するたびにwindowで発生します。このイベントを使用して、

• @localizedデコレータを使用できない場合（例：Litのrender関数を直接使用する場合）に再レンダリングします。

• 読み込みが完了する前でも、ロケールの切り替えが始まるとすぐにレンダリングします（例：読み込みインジケータ）。

• その他のローカライゼーション関連タスク（例：ロケール設定のCookieの設定）を実行します。

detail.status文字列プロパティは、どのような種類のステータス変更が発生したかを知らせ、loading、ready、またはerrorのいずれかになります。

loading

新しいロケールの読み込みが開始されました。

detailオブジェクトには以下が含まれます。

• loadingLocale: string: 読み込みが開始されたロケールのコード。

最初のロケールの読み込みが完了する前に2番目のロケールが要求された場合、新しいloadingイベントがディスパッチされ、最初の要求に対するreadyまたはerrorイベントはディスパッチされません。

loadingステータスは、ready、error、またはloadingステータスで続行できます。

ready

新しいロケールが正常に読み込まれ、レンダリングの準備ができました。

detailオブジェクトには以下が含まれます。

• readyLocale: string: 正常に読み込まれたロケールのコード。

readyステータスは、loadingステータスでのみ続行できます。

error

新しいロケールの読み込みに失敗しました。

detailオブジェクトには以下が含まれます。

• errorLocale: string: 読み込みに失敗したロケールのコード。
• errorMessage: string: ロケール読み込み失敗からのエラーメッセージ。

errorステータスは、loadingステータスでのみ続行できます。

// Show/hide a progress indicator whenever a new locale is loading,
// and re-render the application every time a new locale successfully loads.
window.addEventListener('lit-localize-status', (event) => {
  const spinner = document.querySelector('#spinner');

  if (event.detail.status === 'loading') {
    console.log(`Loading new locale: ${event.detail.loadingLocale}`);
    spinner.removeAttribute('hidden');
  } else if (event.detail.status === 'ready') {
    console.log(`Loaded new locale: ${event.detail.readyLocale}`);
    spinner.setAttribute('hidden', '');
    renderApplication();
  } else if (event.detail.status === 'error') {
    console.error(
      `Error loading locale ${event.detail.errorLocale}: ` +
        event.detail.errorMessage
    );
    spinner.setAttribute('hidden', '');
  }
});

Lit Localizeでは、任意の関数をloadLocaleオプションとして渡すことができるため、ロケールモジュールを自由に読み込むことができます。いくつかの一般的なパターンを以下に示します。

動的インポートを使用して、アクティブになったロケールのみを読み込みます。これは、ユーザーがダウンロードして実行するコードの量を最小限に抑えるため、良いデフォルトです。

import {configureLocalization} from '@lit/localize';
import {sourceLocale, targetLocales} from './generated/locale-codes.js';

const {getLocale, setLocale} = configureLocalization({
  sourceLocale,
  targetLocales,
  loadLocale: (locale) => import(`/locales/${locale}.js`),
});

ページの読み込み時にすべてのロケールの事前読み込みを開始します。動的インポートは、ページ上の残りのスクリプトがロケールモジュールのフェッチ中にブロックされないようにするために使用されます。

import {configureLocalization} from '@lit/localize';
import {sourceLocale, targetLocales} from './generated/locale-codes.js';

const localizedTemplates = new Map(
  targetLocales.map((locale) => [locale, import(`/locales/${locale}.js`)])
);

const {getLocale, setLocale} = configureLocalization({
  sourceLocale,
  targetLocales,
  loadLocale: async (locale) => localizedTemplates.get(locale),
});

静的インポートを使用して、ページ上の他のスクリプトをブロックする形で、すべてのロケールを事前読み込みします。

import {configureLocalization} from '@lit/localize';
import {sourceLocale, targetLocales} from './generated/locale-codes.js';

import * as templates_es_419 from './locales/es-419.js';
import * as templates_zh_hans from './locales/zh-Hans.js';
...

const localizedTemplates = new Map([
  ['es-419', templates_es_419],
  ['zh-Hans', templates_zh_hans],
  ...
]);

const {getLocale, setLocale} = configureLocalization({
  sourceLocale,
  targetLocales,
  loadLocale: async (locale) => localizedTemplates.get(locale),
});

このページを編集する