# Languages and translation

Most sources about a company or a market are written in its own language.
Cormorant searches, fetches and translates across languages so you can
reach them without writing the queries yourself, and keeps every original
next to its translation.

## Language tags

Every language option takes a BCP 47 tag (`en`, `de-CH`, `ja`, `zh-Hans`,
`zh-Hant-TW`) or a plain name: `english`, `german`, `japanese`, `korean`,
`simplified chinese`, `traditional chinese`, `taiwanese`, `cantonese`.
Answers always use the canonical tag. Chinese is told apart by script:
`zh-Hans` (Simplified, mainland China) and `zh-Hant` (Traditional; with
`-TW` or `-HK` for the regional vocabulary). A plain `zh` or `chinese`
means Simplified, and a warning says so.

## Search in several languages

`languages` on `POST /v1/search` (up to six) searches each language in its
own market and merges the results. The query in each language is, in this
order: your own (`queries`), the query itself when it already is in that
language (or converted to the other Chinese script), the company's own name
in that language when `entity` names a company, else a machine translation
that keeps operators, domains, identifiers and names unchanged.
`queries_used` shows what was searched. See
[Search in depth](/docs/search.md#several-languages).

## Fetch a page in a language

`language` on `POST /v1/fetch` asks the site for that language
(Accept-Language and, for a tag with a region such as `zh-Hant-TW` or
`de-CH`, an exit in that country). `meta.language_versions` lists the
page's own versions in other languages, so you can fetch the one you want
instead of translating.

## Translation

`translate_to` adds a machine translation next to the original:

| Where | What is translated | When |
|---|---|---|
| `POST /v1/search` with `languages` | titles and snippets of results in other languages | in the answer |
| `POST /v1/fetch` | the page's title and text | in the answer up to 20,000 characters, else in the background |
| batch fetch items | the page's title and text | in the background |
| `GET /v1/companies/{id}` | purpose, summary, filing and event titles, officers' roles | in the answer |
| `POST /v1/translate` | any text you send | in the answer |

A translation in the background answers `status: pending` with a
`translation_id`; read it with `GET /v1/translations/{id}`. Numbers, names
and identifiers are checked after translation: a segment that fails its
checks is returned untranslated rather than wrong (`status: partial`). A
page already in the target language is not translated and costs nothing.

Translation has two tiers: `quality` (documents, filings) and `fast`
(titles, snippets, queries). It is billed per 1,000 source characters by
tier; text served from the translation cache is billed at the cached rate.
When translation cannot run (switched off, capacity reached) the request
still answers, with `error: translation_unavailable` and a `reason`.

## Companies in their own languages

`GET /v1/companies/search?q=` finds companies by their names in Chinese
(either script, with or without the legal-form ending), Japanese, Korean
and Cyrillic: `q=騰訊` finds Tencent. `translate_to` on a company record adds
the company's own name in that language (from its names, never a machine
translation) and its texts translated.

## Research across languages: collect

`POST /v1/collect` does all of the above in one job: a search per language
for a company or topic, the best pages per language fetched in that
language, a page's language versions merged into one document, and the
pages translated into `translate_to`. Read the documents, with coverage per
language, from `GET /v1/collect/{job_id}`. Each search, fetch and
translation is billed as when made on its own. See the
[API contract](/docs/api.md#collect-post-v1collect).