Langues

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

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 :

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.

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 :

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.