Resolve a Language

The single call, with the response fields explained field by field.

Goal: you have a provider and some spelling of a language. You need the string to send.

curl "https://languages.service.custom.mt/v1/resolve?provider=deepl_api&language=pt_BR"

{
  "query": "pt_BR",
  "provider": "deepl_api",
  "language": "pt-BR",
  "code": "PT-BR",
  "supported": true,
  "match": "exact",
  "matched_alias": null,
  "via_language": null
}

Field	Use it for
`code`	the answer — put this in the provider request
`language`	the canonical code — store this, not `query`
`supported`	`false` means do not attempt the request
`match`	how confident the answer is — see Resolution Ladder
`matched_alias`	which alias matched, when `query` was not canonical
`via_language`	which language supplied the code, for `variant` / `base_language`

Python

import httpx

BASE = "https://languages.service.custom.mt"


def provider_code(provider: str, language: str) -> str:
    response = httpx.get(
        f"{BASE}/v1/resolve", params={"provider": provider, "language": language}, timeout=5.0
    )
    response.raise_for_status()
    body = response.json()
    if not body["supported"]:
        raise ValueError(f"{provider} does not support {body['language']}")
    return body["code"]

Handling the two failure modes

Unknown code — 404 with error.code == "language_not_found". Either the code is genuinely unknown or it needs an alias; see Add a new language.

Known pair, refused — 200 with supported: false and code: null. Someone recorded that this pair does not work. Skip the provider, do not retry.

try:
    code = provider_code("deepl_api", raw_code)
except httpx.HTTPStatusError as exc:
    if exc.response.status_code == 404:
        log.warning("unknown language code", extra={"code": raw_code})
        return None
    raise

Do not skip the call when the code "looks fine"

pt-BR looks fine and is fine for DeepL. It is pt for Amazon. The point of always calling is that your caller stops needing to know which providers are fussy.

Resolve a whole job — both languages in one round trip

Resolve a Language

Python

Handling the two failure modes

Next