本地化最佳实践

每次调用 msg 函数时，它都会返回给定字符串或 Lit 模板的活动区域设置版本。但是，此结果只是一个普通的字符串或模板；它本身不具有在区域设置更改时重新渲染自身的能力。

因此，以确保每次 Lit render 方法运行时都会重新评估 msg 调用，这一点很重要。这样，当区域设置更改时，将返回最新区域设置的正确字符串或模板。

在本地化属性默认值时，很容易在此处犯错。看起来很自然地写成这样

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

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

但是，上述模式没有为默认标签提供在区域设置更改时更新的机会。默认值将卡在元素实例化时碰巧处于活动状态的区域设置的版本上。

一个简单的解决方法是将默认值回退直接移到渲染方法中

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

编辑此页面