Idiomas

Uma associação escreve os seus textos em italiano e, se quiser, também em outro idioma, entre os que o Vimine fala — it, en, zh-Hans, zh-Hant, fr, es, de e pt-BR, hoje. Nem tudo é traduzido, e nada é traduzido por uma máquina: onde a associação não escreveu uma tradução, a API serve o texto italiano dela e avisa você.

Este guia é o que muda para uma integração: como pedir um idioma, como ler a resposta, como dizer ao Vimine em que idioma escrever a uma pessoa.

Pedir um idioma

Toda leitura que devolve textos de uma associação aceita ?locale=:

Leitura
GET /v1/aps/{slug}	tipos de carteirinha, instruções de pagamento, aviso de privacidade
GET /v1/aps/{slug}/events, GET /v1/aps/{slug}/events/{event}	eventos públicos
GET /v1/events, GET /v1/events/{slug}	eventos com um token, incluindo os só para associados

const event = await vimine.public.events.get('circolo-aurora', 'festa-di-primavera', { locale: 'en' });
event.title;   // "Spring party" — se a associação o escreveu
event.locale;  // "en": o título está em inglês. "it": não há tradução, você recebe o texto italiano
event.locales; // ["it", "en"]: os idiomas em que este evento tem um título

Sem ?locale= o idioma é decidido, nesta ordem, por: o idioma que o associado escolheu (com um token de associado), o cabeçalho Accept-Language, o idioma da associação. Um valor que o Vimine não fala (?locale=ja) é ignorado, não é um erro: você recebe o italiano, com locale: "it".

Uma tag regional (en-GB) também é aceita: ela é reduzida ao seu idioma.

Ler a resposta

• locale é o idioma em que veio o texto principal — o título de um evento. Quando não é o que você pediu, a associação não escreveu uma tradução.
• locales são os idiomas em que esse texto existe: use-os para mostrar um seletor só onde ele for útil.
• A substituição acontece campo a campo: um evento pode ter o título em inglês e a descrição em italiano. Nunca misturamos dois idiomas dentro do mesmo texto, e nunca inventamos traduções.

Em GET /v1/aps/{slug}, locale é o idioma da resposta e locales os idiomas que a associação oferece.

O nome da associação, os identificadores (slug, cod) e os documentos jurídicos nunca são traduzidos: o statuto é um ato jurídico, e está em italiano.

As leituras públicas respondem com Content-Language e, quando foi o Accept-Language que decidiu, com Vary: Accept-Language: se você colocar um cache na frente da API, respeite isso — ou passe sempre ?locale=.

O aviso de privacidade tem uma versão por idioma

O aviso de privacidade da associação existe uma vez por idioma, e cada idioma tem a sua própria versão. Se você ler o perfil com ?locale=en e a associação tiver publicado um aviso em inglês, privacy_notice é esse — com locale: "en". Quando você fizer a adesão da pessoa, devolva o que mostrou a ela, idioma incluído:

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
    }
});

A prova que registramos indica aquele documento: o que a pessoa realmente leu.

Dizer em que idioma escrever a uma pessoa

POST /v1/signup, POST /v1/enroll e as inscrições em eventos aceitam locale: o idioma da página que a pessoa preencheu no seu site.

• Ele decide o idioma dos e-mails que vêm depois (confirmação do endereço, boas-vindas, confirmação da inscrição).
• Ele se torna a preferência de uma conta nova. Uma conta que já existe mantém a sua.
• Para um convidado — alguém que se inscreve num evento sem uma conta — é tudo o que sabemos: todos os e-mails que ele recebe estão nesse idioma.

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

Nos e-mails, os textos próprios da associação (o título do evento, as instruções de pagamento) seguem a mesma regra das leituras: em inglês onde a associação os escreveu, em italiano nos outros casos.

O idioma do associado

GET /v1/me devolve locale: o idioma que a pessoa escolheu, ou null se ela nunca escolheu um. Com o escopo profile:write você pode alterá-lo:

await vimine.me.update({ locale: 'en' }); // null apaga a escolha

Aqui — e só aqui — um idioma que o Vimine não fala é um erro: 422 com code: "unsupported" no campo locale. Grave-o só quando a pessoa o escolheu: não o deduza do navegador.

Entrar com Vimine

ui_locales na requisição de autorização é uma lista de preferências, em ordem (ui_locales=ja en): vence o primeiro idioma que o Vimine fala. Se você não indicar nenhum, a página de consentimento segue o idioma do navegador, depois o da associação.