# Idiomas

> Peça os textos de uma associação em outro idioma com ?locale=, entenda por locale e locales o que foi servido, diga em que idioma escrever a uma pessoa. Nunca uma tradução automática.

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

Uma associação escreve os seus textos em italiano e, se quiser, **também em outro idioma**, entre os que o Vimine
fala — `it`, `en`, `zh-Hans`, `zh-Hant`, `fr`, `es`, `de` e `pt-BR`, hoje. Nem tudo é traduzido, e nada é traduzido por uma máquina: onde a associação não escreveu
uma tradução, a API serve o texto italiano dela e **avisa você**.

Este guia é o que muda para uma integração: como pedir um idioma, como ler a resposta, como dizer ao Vimine em que
idioma escrever a uma pessoa.

## Pedir um idioma

Toda leitura que devolve textos de uma associação aceita `?locale=`:

| Leitura | |
|---|---|
| `GET /v1/aps/{slug}` | tipos de carteirinha, instruções de pagamento, aviso de privacidade |
| `GET /v1/aps/{slug}/events`, `GET /v1/aps/{slug}/events/{event}` | eventos públicos |
| `GET /v1/events`, `GET /v1/events/{slug}` | eventos com um token, incluindo os só para associados |

```js
const event = await vimine.public.events.get('circolo-aurora', 'festa-di-primavera', { locale: 'en' });
event.title;   // "Spring party" — se a associação o escreveu
event.locale;  // "en": o título está em inglês. "it": não há tradução, você recebe o texto italiano
event.locales; // ["it", "en"]: os idiomas em que este evento tem um título
```

Sem `?locale=` o idioma é decidido, nesta ordem, por: o idioma que o associado escolheu (com um token de associado), o
cabeçalho `Accept-Language`, o idioma da associação. Um valor que o Vimine não fala (`?locale=ja`) é **ignorado**, não é
um erro: você recebe o italiano, com `locale: "it"`.

Uma tag regional (`en-GB`) também é aceita: ela é reduzida ao seu idioma.

## Ler a resposta

- **`locale`** é o idioma em que veio o texto principal — o título de um evento. Quando não é o que você pediu, a
  associação não escreveu uma tradução.
- **`locales`** são os idiomas em que esse texto existe: use-os para mostrar um seletor só onde ele for útil.
- A substituição acontece **campo a campo**: um evento pode ter o título em inglês e a descrição em italiano. Nunca
  misturamos dois idiomas dentro do mesmo texto, e nunca inventamos traduções.

Em `GET /v1/aps/{slug}`, `locale` é o idioma da resposta e `locales` os idiomas que a associação oferece.

O nome da associação, os identificadores (`slug`, `cod`) e os documentos jurídicos nunca são traduzidos: o statuto é um
ato jurídico, e está em italiano.

As leituras públicas respondem com `Content-Language` e, quando foi o `Accept-Language` que decidiu, com
`Vary: Accept-Language`: se você colocar um cache na frente da API, respeite isso — ou passe sempre `?locale=`.

## O aviso de privacidade tem uma versão por idioma

O aviso de privacidade da associação existe uma vez por idioma, e **cada idioma tem a sua própria versão**. Se você ler o
perfil com `?locale=en` e a associação tiver publicado um aviso em inglês, `privacy_notice` é esse — com
`locale: "en"`. Quando você fizer a adesão da pessoa, devolva o que mostrou a ela, idioma incluído:

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

A prova que registramos indica **aquele** documento: o que a pessoa realmente leu.

## Dizer em que idioma escrever a uma pessoa

`POST /v1/signup`, `POST /v1/enroll` e as inscrições em eventos aceitam `locale`: o idioma da página que a pessoa
preencheu no seu site.

- Ele decide o idioma dos **e-mails que vêm depois** (confirmação do endereço, boas-vindas, confirmação da inscrição).
- Ele se torna a preferência de uma conta **nova**. Uma conta que já existe mantém a sua.
- Para um **convidado** — alguém que se inscreve num evento sem uma conta — é tudo o que sabemos: todos os e-mails que
  ele recebe estão nesse idioma.

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

Nos e-mails, os textos próprios da associação (o título do evento, as instruções de pagamento) seguem a mesma regra das
leituras: em inglês onde a associação os escreveu, em italiano nos outros casos.

## O idioma do associado

`GET /v1/me` devolve `locale`: o idioma que a pessoa escolheu, ou `null` se ela nunca escolheu um. Com o escopo
`profile:write` você pode alterá-lo:

```js
await vimine.me.update({ locale: 'en' }); // null apaga a escolha
```

Aqui — e só aqui — um idioma que o Vimine não fala é um erro: `422` com `code: "unsupported"` no campo `locale`.
Grave-o só quando a pessoa o escolheu: não o deduza do navegador.

## Entrar com Vimine

`ui_locales` na requisição de autorização é uma lista de preferências, em ordem (`ui_locales=ja en`): vence o primeiro
idioma que o Vimine fala. Se você não indicar nenhum, a página de consentimento segue o idioma do navegador, depois o
da associação.