本地化最佳實務

每次呼叫 msg 函式時，它都會傳回以現用語言顯示的指定字串或 Lit 範本。然而，這個結果只是一個普通的字串或範本；它本身並不具備在語言變更時重新渲染的能力。

因此，務必以確保每次執行 Lit render 方法時都會重新評估 msg 呼叫的方式撰寫程式碼。這樣一來，當語言變更時，就會傳回最新語言的正確字串或範本。

這裡很容易犯錯的一種情況是在本地化屬性預設值時。撰寫以下程式碼似乎很自然：

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

或者，可以使用自訂的 getter/setter 來建立更自然的介面：

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 = ...;

編輯此頁面