语言

查看 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 支持的第一种语言为准。如果您没有指定，授权同意页面会依次采用浏览器的语言、协会的语言。