ローカライゼーションのベストプラクティス

msg関数が呼び出されるたびに、アクティブなロケールで指定された文字列またはLitテンプレートのバージョンが返されます。ただし、この結果は通常の文字列またはテンプレートにすぎません。ロケールの変更時に自身を再レンダリングする*固有の*機能はありません。

このため、Litのrenderメソッドが実行されるたびに再評価されるようにmsg呼び出しを記述することが重要です。このようにして、ロケールが変更されると、最新のロケールに対応する正しい文字列またはテンプレートが返されます。

ここで間違いやすい状況の1つは、プロパティのデフォルト値をローカライズする場合です。このように書くのは自然に見えるかもしれません

// Don't do this!
label = msg('Default label')

render() {
  return html`<button>${this.label}</button>`;
}

ただし、上記のパターンでは、ロケールが変更されたときにデフォルトラベルを更新する機会がありません。デフォルト値は、要素がインスタンス化されたときにアクティブだったロケールのバージョンでスタックしてしまいます。

簡単な修正方法は、デフォルト値のフォールバックをrenderメソッドに直接移動することです

render() {
  return html`<button>${this.label ?? msg('Default label')}</button>`;
}

あるいは、カスタムゲッター/セッターを使用して、より自然なインターフェースを作成することもできます

private _label?: string;

@property()
get label() {
  return this._label ?? msg('Default label');
}

set label(label: string) {
  this._label = label;
}

render() {
  return html`<button>${this.label}</button>`;
}

static properties = {
  label: {}
};

get label() {
  return this._label ?? msg('Default label');
}

set label(label) {
  this._label = label;
}

render() {
  return html`<button>${this.label}</button>`;
}

@lit/localizeは、ローカライズされたテンプレート内にHTMLマークアップを埋め込むことを完全にサポートしていますが、可能な限り避けるのが最善です。これは以下の理由によるものです。

1. 翻訳者は、マークアップが埋め込まれたフレーズではなく、単純な文字列フレーズを処理する方が簡単です。

2. 意味を変更せずに外観に影響を与えるクラスを追加する場合など、マークアップが変更されたときに不要な再翻訳作業を回避できます。

3. 通常、ロケールの切り替えが速くなります。これは、DOMの更新が必要な部分が少なくなるためです。また、共通のマークアップを各翻訳に複製する必要がないため、バンドルに含まれるJavaScriptが少なくなります。

理想的ではない

render() {
  // Don't do this! There's no reason to include the <button> tag in this
  // localized template.
  return msg(html`<button>Launch rocket</button>`);
}

理想的

render() {
  // Much better! Now the phrase "Launch rocket" can be translated more easily
  // in isolation.
  return html`<button>${msg('Launch rocket')}</button>`;
}

テンプレートを小さな断片に分割することも役立ちます

render() {
  // Don't do this!
  return msg(html`
  <p>The red button makes the rocket go up.</p>
  <p>The green button makes the rocket do a flip.</p>
  `);
}

render() {
  // Better! No markup needs to be processed by translators, and each sentence
  // can be translated independently.
  return html`
  <p>${msg('The red button makes the rocket go up.')}</p>
  <p>${msg('The green button makes the rocket do a flip.')}</p>
  `;
}

HTMLをローカライズされたテンプレートに*含めるべき*場合もあります。たとえば、フレーズの中央にHTMLタグが必要な場合などです

render() {
  return msg(html`Lift off in <b>T-${this.countdown}</b> seconds`);
}

静的分析は、同じ名前の別の関数ではなく、@lit/localizeのmsg関数と他のAPIをいつ呼び出しているかを判断するために使用されます。

msg関数と他のAPIを再エクスポートまたは再割り当てすることができ、ほとんどの場合、これは正常に機能します。

ただし、特定のパターンは静的分析では理解できないほど動的すぎる場合があります。メッセージが抽出に失敗し、msg関数を再割り当てまたは再エクスポートした場合、これが原因である可能性があります。

関数を@lit/localize APIとして強制的に分析するには、JavaScriptでJSDoc @typeコメントを使用するか、TypeScriptで型キャストを使用します

const myMsg = ... as typeof import('@lit/localize').msg;

/** @type import('@lit/localize').msg */
const myMsg = ...;

このページを編集