# Langues

> Demander le contenu d’une association dans une autre langue avec ?locale=, savoir grâce à locale et locales ce qui a été servi, dire dans quelle langue écrire à une personne. Jamais de traduction automatique.

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

Une association écrit son contenu en italien et, si elle le souhaite, **dans une autre langue aussi**, parmi celles que
Vimine parle — `it`, `en`, `zh-Hans`, `zh-Hant`, `fr`, `es`, `de` et `pt-BR` aujourd’hui. Tout n’est pas traduit, et rien n’est traduit par une machine : là où
l’association n’a écrit aucune traduction, l’API sert son texte italien et **vous le dit**.

Ce guide décrit ce qui change pour une intégration : comment demander une langue, comment lire la réponse, comment dire
à Vimine dans quelle langue écrire à une personne.

## Demander une langue

Chaque lecture qui renvoie du contenu d’une association accepte `?locale=` :

| Lecture | |
|---|---|
| `GET /v1/aps/{slug}` | types d’adhésion, instructions de paiement, notice d’information sur la vie privée |
| `GET /v1/aps/{slug}/events`, `GET /v1/aps/{slug}/events/{event}` | événements publics |
| `GET /v1/events`, `GET /v1/events/{slug}` | événements avec un jeton, y compris ceux réservés aux membres |

```js
const event = await vimine.public.events.get('circolo-aurora', 'festa-di-primavera', { locale: 'en' });
event.title;   // "Spring party" — si l’association l’a écrit
event.locale;  // "en" : le titre est en anglais. "it" : il n’y a pas de traduction, vous avez le texte italien
event.locales; // ["it", "en"] : les langues dans lesquelles cet événement a un titre
```

Sans `?locale=`, la langue est décidée, dans l’ordre, par : la langue choisie par le membre (avec un jeton de membre),
l’en-tête `Accept-Language`, la langue de l’association. Une valeur que Vimine ne parle pas (`?locale=ja`) est
**ignorée**, ce n’est pas une erreur : vous obtenez l’italien, avec `locale: "it"`.

Une étiquette régionale (`en-GB`) est acceptée aussi : elle est ramenée à sa langue.

## Lire la réponse

- **`locale`** est la langue dans laquelle est arrivé le texte principal — le titre d’un événement. Quand ce n’est pas
  celle que vous avez demandée, l’association n’a écrit aucune traduction.
- **`locales`** sont les langues dans lesquelles ce texte existe : utilisez-les pour n’afficher un sélecteur que là où
  il est utile.
- Le remplacement se fait **champ par champ** : un événement peut avoir un titre anglais et une description italienne.
  Nous ne mélangeons jamais deux langues dans un même texte, et nous n’inventons jamais de traductions.

Sur `GET /v1/aps/{slug}`, `locale` est la langue de la réponse et `locales` les langues que l’association propose.

Le nom de l’association, les identifiants (`slug`, `cod`) et les documents juridiques ne sont jamais traduits : le
statuto est un acte juridique, et il est en italien.

Les lectures publiques répondent avec `Content-Language` et, quand `Accept-Language` a décidé, avec
`Vary: Accept-Language` : si vous placez un cache devant l’API, respectez-le — ou passez toujours `?locale=`.

## La notice d’information a une version par langue

La notice d’information sur la vie privée de l’association existe une fois par langue, et **chaque langue a sa propre
version**. Si vous lisez le profil avec `?locale=en` et que l’association a publié une notice en anglais,
`privacy_notice` est celle-ci — avec `locale: "en"`. Quand vous faites adhérer la personne, renvoyez ce que vous lui
avez montré, langue comprise :

```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 preuve que nous enregistrons nomme **ce** document : celui que la personne a réellement lu.

## Dire dans quelle langue écrire à une personne

`POST /v1/signup`, `POST /v1/enroll` et les inscriptions aux événements acceptent `locale` : la langue de la page que
la personne a remplie sur votre site.

- Elle décide de la langue des **e-mails qui suivent** (confirmation de l’adresse, bienvenue, confirmation de
  l’inscription).
- Elle devient la préférence d’un **nouveau** compte. Un compte qui existe déjà garde la sienne.
- Pour un **invité** — une personne qui s’inscrit à un événement sans compte — c’est tout ce que nous savons : chaque
  e-mail qu’il reçoit est dans cette langue.

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

Dans les e-mails, le contenu propre à l’association (le titre de l’événement, les instructions de paiement) suit la
même règle que les lectures : en anglais là où l’association l’a écrit, en italien sinon.

## La langue du membre

`GET /v1/me` renvoie `locale` : la langue choisie par la personne, ou `null` si elle n’en a jamais choisi. Avec le
scope `profile:write`, vous pouvez la changer :

```js
await vimine.me.update({ locale: 'en' }); // null efface le choix
```

Ici — et seulement ici — une langue que Vimine ne parle pas est une erreur : `422` avec `code: "unsupported"` sur le
champ `locale`. Ne l’écrivez que quand la personne l’a choisie : ne la déduisez pas du navigateur.

## Se connecter avec Vimine

`ui_locales` dans la requête d’autorisation est une liste de préférences, dans l’ordre (`ui_locales=ja en`) : la
première langue que Vimine parle l’emporte. Si vous n’en nommez aucune, la page de consentement suit la langue du
navigateur, puis celle de l’association.