準備元件以供翻譯

若要準備你的專案以供翻譯，請完成下列動作。

• 使用 i18n 屬性標記元件範本中的文字
• 使用 i18n- 屬性標記元件範本中的屬性文字字串
• 使用 $localize 標記訊息字串標記元件程式碼中的文字字串

標記元件範本中的文字

在元件範本中，i18n 中繼資料就是 i18n 屬性的值。

<element i18n="{i18n_metadata}">{string_to_translate}</element>

使用 i18n 屬性，在元件範本中標記要翻譯的靜態文字訊息。 將它放在每個包含要翻譯的固定文字的元素標籤上。

i18n 範例

下列 <h1> 標籤顯示一句簡單的英文問候語「Hello i18n!」。

<h1>Hello i18n!</h1>

若要標記這句問候語以供翻譯，請將 i18n 屬性加入 <h1> 標籤。

<h1 i18n>Hello i18n!</h1>

搭配條件陳述式使用 i18n

下列 <div> 標籤會依切換狀態，將翻譯後的文字顯示為 div 內容與 aria-label 的一部分

<button type="button" (click)="toggleDisplay()">Toggle</button>
<div i18n [attr.aria-label]="toggleAriaLabel()">{{ toggle() }}</div>

import {Component, computed, signal} from '@angular/core';
import {$localize} from '@angular/localize/init';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  minutes = 0;
  gender = 'female';
  fly = true;
  logo = '${this.baseUrl}/angular.svg';
  readonly toggle = signal(false);
  readonly toggleAriaLabel = computed(() => {
    return this.toggle()
      ? $localize`:Toggle Button|A button to toggle status:Show`
      : $localize`:Toggle Button|A button to toggle status:Hide`;
  });

  inc(i: number) {
    this.minutes = Math.min(5, Math.max(0, this.minutes + i));
  }
  male() {
    this.gender = 'male';
  }
  female() {
    this.gender = 'female';
  }
  other() {
    this.gender = 'other';
  }
  toggleDisplay() {
    this.toggle.update((toggle) => !toggle);
  }
}

翻譯沒有 HTML 元素的行內文字

使用 <ng-container> 元素，為特定文字關聯翻譯行為，同時不改變文字的顯示方式。

<ng-container i18n>I don't output any element</ng-container>

為插值預留位置命名

預設情況下，Angular 會為翻譯訊息中的每個插值產生一個預留位置名稱。若要給它一個有意義、能協助譯者理解上下文的名稱，請在插值內加入 //i18n(ph="name") 註解。

<element i18n>{{ expression //i18n(ph="placeholder_name") }}</element>

例如：

<p i18n>Hello, {{ username //i18n(ph="name") }}!</p>

這相當於在元件程式碼中以 $localize 為預留位置命名：

$localize`Hello, ${username}:name:!`;

標記元素屬性以供翻譯

在元件範本中，i18n 中繼資料就是 i18n-{attribute_name} 屬性的值。

<element i18n-{attribute_name}="{i18n_metadata}" {attribute_name}="{attribute_value}" />

HTML 元素的屬性包含一些文字，應該與元件範本中其餘顯示的文字一起翻譯。

將 i18n-{attribute_name} 用在任何元素的任何屬性上，並將 {attribute_name} 換成該屬性的名稱。 使用下列語法指派意義、說明與自訂 ID。

i18n-{attribute_name}="{meaning}|{description}@@{id}"

i18n-title 範例

若要翻譯圖片的標題，請看這個範例。 下列範例顯示一張帶有 title 屬性的圖片。

<img [src]="logo" title="Angular logo" alt="Angular logo" />

若要標記 title 屬性以供翻譯，請完成下列動作。

加入 i18n-title 屬性

下列範例顯示如何加入 i18n-title，標記 img 標籤上的 title 屬性。

<img [src]="logo" i18n-title title="Angular logo" alt="Angular logo" />

標記元件程式碼中的文字

在元件程式碼中，翻譯來源文字與中繼資料被反引號 (`) 字元包圍。

使用 $localize 標記訊息字串，標記程式碼中要翻譯的字串。

$localize`string_to_translate`;

i18n 中繼資料被冒號 (:) 字元包圍，並位於翻譯來源文字之前。

$localize`:{i18n_metadata}:string_to_translate`;

包含插值文字

在 $localize 標記訊息字串中包含插值。

$localize`string_to_translate ${variable_name}`;

在程式碼中為插值預留位置命名

$localize`string_to_translate ${variable_name}:placeholder_name:`;

翻譯的條件語法

return this.show ? $localize`Show Tabs` : $localize`Hide tabs`;

供翻譯使用的 i18n 中繼資料

{meaning}|{description}@@{custom_id}

下列參數提供上下文與額外資訊，減少譯者的混淆。

關於自訂 ID 的更多資訊，請見以自訂 ID 管理標記的文字。

加入有幫助的說明與意義

若要正確翻譯文字訊息，請為譯者提供額外資訊或上下文。

將文字訊息的_說明_作為 i18n 屬性或 $localize 標記訊息字串的值加入。

下列範例顯示 i18n 屬性的值。

<h1 i18n="An introduction header for this sample">Hello i18n!</h1>

下列範例顯示帶有說明的 $localize 標記訊息字串的值。

$localize`:An introduction header for this sample:Hello i18n!`;

譯者也可能需要知道文字訊息在這個特定應用程式上下文中的意義或意圖，才能將它以與其他相同意義文字一致的方式翻譯。 讓 i18n 屬性值以_意義_開頭，並以 | 字元將它與_說明_分隔：{meaning}|{description}。

h1 範例

例如，你可能想指定 <h1> 標籤是網站標題，需要以相同方式翻譯，不論它是用作標題，還是在另一段文字中被參照。

下列範例顯示如何指定 <h1> 標籤必須翻譯為標題，或在其他地方被參照。

<h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1>

結果是任何標記了 site header 的文字，都會因為_意義_相同而被完全一致地翻譯。

下列程式碼範例顯示帶有意義與說明的 $localize 標記訊息字串的值。

$localize`:site header|An introduction header for this sample:Hello i18n!`;

ICU 運算式

ICU 運算式能協助你在元件範本中標記符合條件的替代文字。 ICU 運算式包含一個元件屬性、一個 ICU 子句，以及被左大括號 ({) 與右大括號 (}) 字元包圍的 case 陳述式。

{ component_property, icu_clause, case_statements }

元件屬性定義了變數。 ICU 子句定義了條件文字的型別。

若要簡化翻譯，請將 International Components for Unicode 子句（ICU 子句）與正規運算式搭配使用。

標記複數

不同語言有不同的複數規則，增加了翻譯的難度。 由於其他地區設定表達基數的方式不同，你可能需要設定與英文不一致的複數類別。 使用 plural 子句，標記逐字翻譯可能失去意義的運算式。

{ component_property, plural, pluralization_categories }

在複數類別之後，輸入被左大括號 ({) 與右大括號 (}) 字元包圍的預設文字 (英文)。

pluralization_category { }

下列複數類別可用於英文，並可能依地區設定而有所不同。

若沒有任何複數類別相符，Angular 會使用 other，作為類別缺失時的標準備援。

other { default_quantity }

function plural(n: number): number {
  let i = Math.floor(Math.abs(n)),
    v = n.toString().replace(/^[^.]*\.?/, '').length;
  if (i === 1 && v === 0) return 1;
  return 5;
}

minutes 範例

若你想以英文顯示下列片語，其中 x 是一個數字。

updated x minutes ago

而且你也想依 x 的基數顯示下列片語。

updated just now

updated one minute ago

使用 HTML 標記與插值。 下列程式碼範例顯示如何使用 plural 子句，在 <span> 元素中表達前述三種情況。

<span i18n
  >Updated
  {minutes, plural, =0 {just now} =1 {one minute ago} other {{{ minutes }} minutes ago}}</span
>

請檢視上一個程式碼範例中的下列細節。

{{minutes}} 是一種插值。

標記替代項與巢狀運算式

select 子句依你定義的字串值，標記替代文字的選項。

{ component_property, select, selection_categories }

翻譯所有的替代項，依變數的值顯示替代文字。

在選取類別之後，輸入被左大括號 ({) 與右大括號 (}) 字元包圍的文字 (英文)。

selection_category { text }

不同地區設定有不同的文法結構，增加了翻譯的難度。 使用 HTML 標記。 若沒有任何選取類別相符，Angular 會使用 other，作為類別缺失時的標準備援。

other { default_value }

gender 範例

若你想以英文顯示下列片語。

The author is other

而且你也想依元件的 gender 屬性顯示下列片語。

The author is female

The author is male

下列程式碼範例顯示如何繫結元件的 gender 屬性，並使用 select 子句在 <span> 元素中表達前述三種情況。

gender 屬性將輸出繫結至下列每個字串值。

select 子句將這些值對應到適當的翻譯。 下列程式碼範例顯示 gender 屬性搭配 select 子句的使用方式。

<span i18n>The author is {gender, select, male {male} female {female} other {other}}</span>

gender 與 minutes 範例

將不同的子句組合在一起，例如 plural 與 select 子句。 下列程式碼範例顯示以 gender 與 minutes 範例為基礎的巢狀子句。

<span i18n
  >Updated:
  {minutes, plural,
    =0 {just now}
    =1 {one minute ago}
    other {{{ minutes }} minutes ago by {gender, select, male {male} female {female} other {other}}}
  }
</span>

下一步