語言

檢視 Markdown

協會用義大利語撰寫自己的文案；如果願意，還可以用另一種語言撰寫，只要是 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}`	使用權杖讀取的活動，包括僅限會員的活動

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"。為當事人辦理入會時，請把您展示給他的內容原樣傳回，包括語言：

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：當事人在您網站上填寫的頁面的語言。

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

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 時，您可以更改它：

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

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

使用 Vimine 登入

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