Formality

Many European languages force a choice the English source never made: Sie or du, vous or tu, usted or tú. The formality parameter makes that choice explicit instead of leaving it to chance.

Values

curl -X POST https://api.vizvuz.com/v1/translate \
  -H "Authorization: Bearer vz_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "text": ["Could you send us the file?"],
        "target_lang": "DE",
        "formality": "more" }'

{ "translations": [ { "detected_source_language": "EN",
                      "text": "Könnten Sie uns die Datei senden?" } ] }

With "formality": "less" the same sentence becomes „Könntest du uns die Datei schicken?".

Which languages support it

Check supports_formality in GET /v1/languages?type=target. It is true for almost every target and false for English (EN-GB, EN-US), Irish, Icelandic and Maltese, which have no productive formal/informal distinction to switch between.

more/less versus prefer_more/prefer_less

This distinction matters and the two pairs behave differently:

• more or less on a language that does not support formality is an error.

The request answers 400 with validation_error, telling you to use prefer_more/prefer_less instead.

• prefer_more or prefer_less never error on this. Formality is applied

where the target supports it and silently ignored where it does not.

If your client translates into more than one target language and you cannot guarantee every one of them supports formality, set prefer_more or prefer_less rather than more/less — that is exactly what the prefer_ variants exist for. Reach for the plain more/less only when you already know the target supports it, or want the request to fail loudly if it does not.

Consistency across a batch

Formality applies to the whole request. If you send fifty texts, all fifty are translated in the same register — which is what you want for a UI, a product catalogue or a set of e-mail templates.

If parts of one document need different registers, send them as separate requests.

Formality and glossaries

A glossary wins. If a glossary maps a term to a specific translation, that translation is used regardless of the formality setting. Use this deliberately: put your fixed address forms and salutations in a glossary, and let formality handle the rest of the sentence.

Formality and caching

The formality value is part of the cache key. The same sentence with more and with less are two different cache entries, and both are billed the first time you ask for them.

Choosing a default for your product

• Business software, invoices, legal notices: more, or prefer_more if you

translate into languages you do not control the list of. In German, Dutch and the Nordic business context, informal address in an invoice reads as a mistake.

• Consumer apps, games, marketing to a young audience: less or

prefer_less.

• User-generated content, chat messages: default. The engine follows the

register of the source, which is usually right.