Formality control

French, German, Spanish, Polish and most other targets distinguish between a formal and an informal way of addressing the reader. English source text does not carry that information, so the engine has to choose. The formality parameter lets you choose instead.

Parameter values

The value is case-insensitive. Anything outside these five is a validation_error.

Example

A support reply translated into French, first formally, then informally:

curl https://api.langapi.xyz/v1/translate \
  -X POST \
  -H "Authorization: Bearer la_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "text": ["Thank you for your patience. We have refunded your payment."],
        "source_lang": "EN",
        "target_lang": "FR",
        "formality": "prefer_more"
      }'

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Merci de votre patience. Nous avons remboursé votre paiement."
    }
  ]
}

With "formality": "less" the same request yields « Merci pour ta patience. Nous avons remboursé ton paiement. »

Strict versus preferring

more and less are strict: on a target whose supports_formality flag is false, the request is rejected with 400 validation_error and the message points you to the prefer_ variants. Use the strict form when you know the target and want a loud failure if someone changes it.

prefer_more and prefer_less never fail on this account. On a supporting target they act exactly like more and less; on any other target the parameter is dropped. Use them whenever the target language is data rather than a constant — a loop over a list of locales, a user-selected language.

Targets without a register switch

Every other target reports supports_formality: true in GET /v1/languages?type=target. See Supported language codes.

Scope within a request

The setting applies to all entries of text in the request. A batch of fifty strings is translated in one register. If one document needs two registers — a formal cover letter and an informal chat transcript — send them as two requests.

Interaction with glossaries and the cache

• A glossary entry overrides formality. If the glossary maps a greeting to a

specific rendering, that rendering is used whatever the register.

• The formality value is part of the cache key. Translating the same string

with more and then with less produces two independent cache entries, and both are charged the first time.

• Every cached entry was produced with a specific formality; a change to the

parameter never returns a result computed under the other one.

Picking a default

• Transactional e-mail, invoices, terms, B2B software: prefer_more. In

German, Dutch and the Nordic languages an informal invoice reads as careless.

• Consumer apps, games, social features: prefer_less.
• User-generated text, chat, reviews: default. The engine will mirror the

register of the source, which is usually the right call.