Lingue

Un’associazione scrive i suoi testi in italiano e, se vuole, anche in un’altra lingua tra quelle che Vimine parla — oggi it, en, zh-Hans, zh-Hant, fr, es, de e pt-BR. Non tutto viene tradotto, e niente viene tradotto da una macchina: dove l’associazione non ha scritto una traduzione, l’API serve il suo testo italiano e te lo dice.

Questa guida è che cosa cambia per un’integrazione: come si chiede una lingua, come si legge la risposta, come si dice a Vimine in che lingua scrivere a una persona.

Chiedere una lingua

Ogni lettura che restituisce testi dell’associazione accetta ?locale=:

Lettura
GET /v1/aps/{slug}	tipi di tessera, istruzioni di pagamento, informativa privacy
GET /v1/aps/{slug}/events, GET /v1/aps/{slug}/events/{event}	eventi pubblici
GET /v1/events, GET /v1/events/{slug}	eventi con un token, riservati ai soci compresi

const event = await vimine.public.events.get('circolo-aurora', 'festa-di-primavera', { locale: 'en' });
event.title;   // "Spring party" — se l'associazione l'ha scritto
event.locale;  // "en": il titolo è in inglese. "it": non c'è traduzione, hai il testo italiano
event.locales; // ["it", "en"]: le lingue in cui questo evento ha un titolo

Senza ?locale= decide, nell’ordine: la lingua scelta dal socio (con un token del socio), l’header Accept-Language, la lingua dell’associazione. Un valore che Vimine non parla (?locale=ja) viene ignorato, non è un errore: ricevi l’italiano, con locale: "it".

Accetta anche un tag regionale (en-GB): viene ridotto alla lingua.

Leggere la risposta

• locale è la lingua in cui ti è arrivato il testo principale — il titolo di un evento. Se non è quella che avevi chiesto, l’associazione non ha scritto una traduzione.
• locales sono le lingue in cui quel testo esiste: usale per mostrare un selettore solo dove serve.
• La sostituzione è campo per campo: un evento può avere il titolo in inglese e la descrizione in italiano. Non mescoliamo mai due lingue dentro lo stesso testo, e non inventiamo traduzioni.

Su GET /v1/aps/{slug}, locale è la lingua della risposta e locales le lingue che l’associazione offre.

Non vengono mai tradotti il nome dell’associazione, gli identificativi (slug, cod) e i documenti legali: lo statuto è un atto, ed è in italiano.

Le letture pubbliche rispondono con Content-Language e, quando a decidere è stato Accept-Language, con Vary: Accept-Language: se metti una cache davanti all’API, rispettalo — oppure passa sempre ?locale=.

L’informativa privacy ha una versione per lingua

L’informativa dell’associazione esiste una volta per lingua, e ogni lingua ha la sua versione. Se leggi il profilo con ?locale=en e l’associazione ha pubblicato un’informativa in inglese, privacy_notice è quella — con locale: "en". Quando iscrivi la persona, rimanda indietro ciò che le hai mostrato, lingua compresa:

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

La prova che registriamo nomina quel documento: quello che la persona ha letto davvero.

Dire in che lingua scrivere a una persona

POST /v1/signup, POST /v1/enroll e le iscrizioni agli eventi accettano locale: la lingua della pagina che la persona ha compilato sul tuo sito.

• Decide la lingua delle mail che seguono (la conferma dell’indirizzo, il benvenuto, la conferma dell’iscrizione).
• Diventa la preferenza di un account nuovo. Un account che esiste già tiene la sua.
• Per un ospite — chi si iscrive a un evento senza account — è tutto ciò che sappiamo: ogni mail che riceve è in quella lingua.

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

Nelle mail, i testi dell’associazione (il titolo dell’evento, le istruzioni di pagamento) seguono la stessa regola delle letture: in inglese dove l’associazione li ha scritti, in italiano altrimenti.

La lingua del socio

GET /v1/me restituisce locale: la lingua che la persona ha scelto, o null se non ne ha mai scelta una. Con lo scope profile:write puoi cambiarla:

await vimine.me.update({ locale: 'en' }); // null azzera la scelta

Qui — e solo qui — una lingua che Vimine non parla è un errore: 422 con code: "unsupported" sul campo locale. Scrivila solo quando la persona l’ha scelta: non dedurla dal browser.

Accesso con Vimine

ui_locales sulla richiesta di autorizzazione è una lista di preferenze, nell’ordine (ui_locales=ja en): vale la prima lingua che Vimine parla. Se non ne indichi, la pagina di consenso segue la lingua del browser, poi quella dell’associazione.