# Lingue

> Chiedere i testi di un'associazione in un'altra lingua con ?locale=, capire da locale e locales che cosa è stato servito, dire in che lingua scrivere a una persona. Mai una traduzione automatica.

URL: https://developers.vimine.network/guides/languages/

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 |

```js
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:

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

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.

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

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:

```js
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.