# Sprachen

> Die Texte eines Vereins mit ?locale= in einer anderen Sprache anfordern, an locale und locales erkennen, was geliefert wurde, sagen, in welcher Sprache einer Person geschrieben wird. Nie eine maschinelle Übersetzung.

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

Ein Verein schreibt seine Texte auf Italienisch und, wenn er möchte, **auch in einer anderen Sprache**, unter denen, die Vimine
spricht — heute `it`, `en`, `zh-Hans`, `zh-Hant`, `fr`, `es`, `de` und `pt-BR`. Nicht alles wird übersetzt, und nichts wird maschinell übersetzt: Wo der
Verein keine Übersetzung geschrieben hat, liefert die API seinen italienischen Text und **sagt es Ihnen**.

Diese Anleitung beschreibt, was sich für eine Integration ändert: wie Sie eine Sprache anfordern, wie Sie die Antwort lesen, wie Sie Vimine sagen,
in welcher Sprache einer Person geschrieben werden soll.

## Eine Sprache anfordern

Jeder Lesezugriff, der Texte eines Vereins liefert, nimmt `?locale=`:

| Lesezugriff | |
|---|---|
| `GET /v1/aps/{slug}` | Mitgliedsarten, Zahlungsanweisungen, Datenschutzhinweise |
| `GET /v1/aps/{slug}/events`, `GET /v1/aps/{slug}/events/{event}` | öffentliche Veranstaltungen |
| `GET /v1/events`, `GET /v1/events/{slug}` | Veranstaltungen mit einem Token, einschließlich derer nur für Mitglieder |

```js
const event = await vimine.public.events.get('circolo-aurora', 'festa-di-primavera', { locale: 'en' });
event.title;   // "Spring party" — wenn der Verein ihn geschrieben hat
event.locale;  // "en": Der Titel ist auf Englisch. "it": Es gibt keine Übersetzung, Sie haben den italienischen Text
event.locales; // ["it", "en"]: die Sprachen, in denen diese Veranstaltung einen Titel hat
```

Ohne `?locale=` entscheidet über die Sprache, der Reihe nach: die Sprache, die das Mitglied gewählt hat (mit einem Mitglieder-Token), der
Header `Accept-Language`, die Sprache des Vereins. Ein Wert, den Vimine nicht spricht (`?locale=ja`), wird **ignoriert**, er
ist kein Fehler: Sie erhalten Italienisch, mit `locale: "it"`.

Auch ein regionales Tag (`en-GB`) wird akzeptiert: Es wird auf seine Sprache reduziert.

## Die Antwort lesen

- **`locale`** ist die Sprache, in der der Haupttext — der Titel einer Veranstaltung — geliefert wurde. Ist sie nicht die angeforderte, hat der
  Verein keine Übersetzung geschrieben.
- **`locales`** sind die Sprachen, in denen dieser Text existiert: Nutzen Sie sie, um eine Sprachauswahl nur dort zu zeigen, wo sie sinnvoll ist.
- Der Ersatz geschieht **Feld für Feld**: Eine Veranstaltung kann einen englischen Titel und eine italienische Beschreibung haben. Wir
  mischen nie zwei Sprachen im selben Text, und wir erfinden nie Übersetzungen.

Bei `GET /v1/aps/{slug}` ist `locale` die Sprache der Antwort und `locales` die Sprachen, die der Verein anbietet.

Der Name des Vereins, die Kennungen (`slug`, `cod`) und die rechtlichen Dokumente werden nie übersetzt: Das Statuto ist ein
Rechtsakt, und es ist auf Italienisch.

Öffentliche Lesezugriffe antworten mit `Content-Language` und, wenn `Accept-Language` entschieden hat, mit `Vary: Accept-Language`: Wenn Sie
einen Cache vor die API setzen, beachten Sie das — oder übergeben Sie immer `?locale=`.

## Die Datenschutzhinweise haben eine Version pro Sprache

Die Datenschutzhinweise des Vereins gibt es einmal pro Sprache, und **jede Sprache hat ihre eigene Version**. Wenn Sie das
Profil mit `?locale=en` lesen und der Verein englische Hinweise veröffentlicht hat, ist `privacy_notice` diese — mit
`locale: "en"`. Wenn Sie die Person aufnehmen, senden Sie zurück, was Sie ihr gezeigt haben, einschließlich der Sprache:

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

Der Nachweis, den wir speichern, nennt **dieses** Dokument: das, das die Person tatsächlich gelesen hat.

## Sagen, in welcher Sprache einer Person geschrieben wird

`POST /v1/signup`, `POST /v1/enroll` und die Anmeldungen zu Veranstaltungen nehmen `locale`: die Sprache der Seite, die die Person
auf Ihrer Website ausgefüllt hat.

- Sie bestimmt die Sprache der **folgenden E-Mails** (Bestätigung der Adresse, Willkommen, Bestätigung der Anmeldung).
- Sie wird zur Einstellung eines **neuen** Kontos. Ein bereits bestehendes Konto behält seine eigene.
- Bei einem **Gast** — jemandem, der sich ohne Konto zu einer Veranstaltung anmeldet — ist sie alles, was wir wissen: Jede E-Mail, die er
  erhält, ist in dieser Sprache.

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

In den E-Mails folgen die eigenen Texte des Vereins (der Titel der Veranstaltung, die Zahlungsanweisungen) derselben Regel wie die
Lesezugriffe: auf Englisch, wo der Verein sie geschrieben hat, sonst auf Italienisch.

## Die Sprache des Mitglieds

`GET /v1/me` liefert `locale`: die Sprache, die die Person gewählt hat, oder `null`, wenn sie nie eine gewählt hat. Mit dem
Scope `profile:write` können Sie sie ändern:

```js
await vimine.me.update({ locale: 'en' }); // null löscht die Wahl
```

Hier — und nur hier — ist eine Sprache, die Vimine nicht spricht, ein Fehler: `422` mit `code: "unsupported"` auf dem
Feld `locale`. Schreiben Sie sie nur, wenn die Person sie gewählt hat: Leiten Sie sie nicht aus dem Browser ab.

## Mit Vimine anmelden

`ui_locales` in der Autorisierungsanfrage ist eine Präferenzliste, der Reihe nach (`ui_locales=ja en`): Die erste Sprache, die
Vimine spricht, gewinnt. Wenn Sie keine nennen, folgt die Einwilligungsseite der Sprache des Browsers, dann der des Vereins.