# 語言

> 用 ?locale= 取得協會文案的其他語言版本，從 locale 和 locales 判斷實際傳回了什麼，告訴 Vimine 用哪種語言給某人寫信。絕不使用機器翻譯。

URL: https://developers.vimine.network/zh-hant/guides/languages/

協會用義大利語撰寫自己的文案；如果願意，**還可以用另一種語言**撰寫，只要是 Vimine 支援的語言——目前為 `it`、`en`、`zh-Hans`、`zh-Hant`、`fr`、`es`、`de` 和 `pt-BR`。並非所有內容都有譯文，也沒有任何內容由機器翻譯：協會沒有撰寫譯文的地方，API 會傳回其義大利語文字，並且**明確告訴您**。

本指南說明對整合而言有哪些變化：如何請求某種語言，如何解讀回應，如何告訴 Vimine 用哪種語言給某人寫信。

## 請求某種語言

每個傳回協會文案的讀取介面都接受 `?locale=`：

| 讀取介面 | |
|---|---|
| `GET /v1/aps/{slug}` | 會員卡類型、付款說明、隱私權聲明 |
| `GET /v1/aps/{slug}/events`、`GET /v1/aps/{slug}/events/{event}` | 公開活動 |
| `GET /v1/events`、`GET /v1/events/{slug}` | 使用權杖讀取的活動，包括僅限會員的活動 |

```js
const event = await vimine.public.events.get('circolo-aurora', 'festa-di-primavera', { locale: 'en' });
event.title;   // "Spring party" — 如果協會撰寫了英文標題
event.locale;  // "en"：標題是英文。"it"：沒有譯文，您拿到的是義大利語文字
event.locales; // ["it", "en"]：該活動有標題的語言
```

不帶 `?locale=` 時，語言依次由以下因素決定：會員選擇的語言（使用會員權杖時）、`Accept-Language` 請求標頭、協會的語言。Vimine 不支援的值（`?locale=ja`）會被**忽略**，這不是錯誤：您會得到義大利語，並帶有 `locale: "it"`。

也接受帶地區的語言標籤（`en-GB`）：它會被歸併為對應的語言。

## 解讀回應

- **`locale`** 是主要文字（例如活動標題）實際傳回的語言。如果它不是您請求的語言，說明協會沒有撰寫譯文。
- **`locales`** 是該文字已有的語言：請用它只在有意義的地方顯示語言切換器。
- 替換是**逐欄位**進行的：一個活動可能標題是英文、描述是義大利語。我們絕不在同一段文字中混用兩種語言，也絕不編造譯文。

在 `GET /v1/aps/{slug}` 上，`locale` 是回應的語言，`locales` 是協會提供的語言。

協會名稱、識別碼（`slug`、`cod`）和法律文件永遠不會被翻譯：章程是一份法律文書，以義大利語為準。

公開讀取介面的回應帶有 `Content-Language`；當由 `Accept-Language` 決定語言時，還帶有 `Vary: Accept-Language`：如果您在 API 前面放置了快取，請遵守它——或者始終傳入 `?locale=`。

## 隱私權聲明每種語言各有一個版本

協會的隱私權聲明每種語言各有一份，而且**每種語言都有自己的版本號**。如果您用 `?locale=en` 讀取資料，而協會發布了英文隱私權聲明，那麼 `privacy_notice` 就是這一份——帶有 `locale: "en"`。為當事人辦理入會時，請把您展示給他的內容原樣傳回，包括語言：

```js
const profile = await vimine.public.association('circolo-aurora', { locale: 'en' });

await vimineServer.enroll({
    // …
    locale: 'en',
    privacy_notice: {
        version: profile.privacy_notice.version,
        sha256: profile.privacy_notice.sha256,
        locale: profile.privacy_notice.locale
    }
});
```

我們記錄的證明指向的是**這一份**文件：當事人真正閱讀過的那一份。

## 告訴 Vimine 用哪種語言給某人寫信

`POST /v1/signup`、`POST /v1/enroll` 和活動報名都接受 `locale`：當事人在您網站上填寫的頁面的語言。

- 它決定**後續郵件**的語言（電子郵件地址確認、歡迎郵件、報名確認）。
- 它會成為**新**帳戶的語言偏好。已存在的帳戶保留其原有偏好。
- 對於**嘉賓**——沒有帳戶而報名活動的人——這是我們掌握的唯一資訊：他收到的每封郵件都使用該語言。

```js
await vimineServer.registrations.guest('festa-di-primavera', {
    email: 'marie.dupont@example.org',
    first_name: 'Marie',
    last_name: 'Dupont',
    registration_type: type.uid,
    locale: 'en'
});
```

在郵件中，協會自己的文案（活動標題、付款說明）遵循與讀取介面相同的規則：協會撰寫了該語言版本的就用該語言，否則用義大利語。

## 會員的語言

`GET /v1/me` 傳回 `locale`：當事人選擇的語言；如果從未選擇過，則為 `null`。擁有 `profile:write` scope 時，您可以更改它：

```js
await vimine.me.update({ locale: 'en' }); // null 清除所選語言
```

在這裡——且僅在這裡——Vimine 不支援的語言才是錯誤：傳回 `422`，`locale` 欄位上帶有 `code: "unsupported"`。只有在當事人自己選擇了語言時才寫入：不要根據瀏覽器推斷。

## 使用 Vimine 登入

授權請求中的 `ui_locales` 是按順序排列的偏好清單（`ui_locales=ja en`）：以 Vimine 支援的第一種語言為準。如果您沒有指定，授權同意頁面會依次採用瀏覽器的語言、協會的語言。