Skip to the content

Languages

Accept-Language for labels and messages, the answer language of a lookup, and tariff_language, the edition of Japan's tariff text.

Two settings decide the language of what the API returns. Accept-Language is per request and governs labels and messages. The answer language is per lookup and governs the text written for that lookup. A third, the tariff language, chooses the edition of the tariff text for the market JP (The tariff language).

Supported languages: English (en), Vietnamese (vi), Japanese (ja) and Korean (ko).

Send Accept-Language with one of the four codes. A tag with a region is read by its language (en-US is en), quality values are honoured, and the first supported language wins. Without the header, or with no supported language in it, the service answers in its default language. The answer names its language in Content-Language.

curl https://htspilot.com/api/lookups/f4a2251d5dc941ec99f7d459e05082a5 \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -H "Accept-Language: ja"

What follows Accept-Language:

  • error messages (detail);
  • status and decision labels (status_label, decision_label), role labels, country names;
  • review flags: the message of each entry of review_flags and of result.flags;
  • the names of the checks, the disclaimer and the legal notes of a result;
  • the Excel templates and the Excel results of a batch.

The machine values next to a label do not change with the language: status, decision, the code of a review flag. Branch on those, show the labels.

A lookup has a language of its own, returned as language. It is set when the lookup is created:

  1. the language field of POST /api/classify, when it is sent (en, vi, ja or ko; a tag with a region is read by its language);
  2. otherwise the language of the request, from Accept-Language.

A rerun (POST /api/lookups/{lookup_id}/rerun) keeps the language of the lookup it continues, unless the request names another language.

curl -X POST https://htspilot.com/api/classify \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"description": "Stainless steel vacuum flask, 500 ml", "market": "US", "language": "ko"}'

What is written in the answer language, for every reader, whatever their Accept-Language:

  • the written reasons for choosing or ruling out a code, the summary and the open uncertainties;
  • the missing information (missing_info);
  • the questions with their options (result.questions);
  • the legal findings and the warnings.

So a lookup created in Korean reads in Korean to everyone, while its review flags and status labels appear in the language of whoever reads it.

The tariff text is the text of the schedule itself: the description of a line and the line with its parents. Japan Customs publishes Japan's Tariff Schedule in two official editions, one in English and one in Japanese. For the market JP, the field tariff_language (en or ja, en when it is not sent) chooses the edition, and it is the only thing that does. It is not Accept-Language, and it is not language:

Setting Chooses the language of Set with
Accept-Language The messages and the labels The header of each request
language The reasons written for a lookup The field of a classify request
tariff_language The official text of the tariff lines (JP only) The field of a request, or a query parameter

Each edition is a dataset of its own, and ja reads the Japanese one (Tariff data): description and full_description of the lines are the Japanese edition's text, and translations.en holds the English edition's. A lookup can read in Korean with tariff lines in Japanese. Every other market offers en alone and answers 422 to another value (Tariff data). tariff_languages of GET /api/datasets lists what each market offers.

Part of a lookup Follows
status_label, decision_label The reader (Accept-Language)
review_flags, result.flags The reader
Names of checks, disclaimer, legal notes The reader
Reasons, summary, uncertainties The lookup (language)
missing_info, result.questions and their options The lookup
Legal findings, warnings The lookup
Official tariff descriptions Not translated: as published. For JP, the edition named by tariff_language

This changed: questions, missing information and legal findings used to follow Accept-Language on every read. A client that relied on the header for them now sets language when it creates the lookup.

Notes

  • A product description can be written in English, Vietnamese, Japanese or Korean, whatever the answer language.
  • Texts that live in the tariff data and the legal notes exist in Vietnamese and English; Japanese and Korean readers get the English text.
  • Japan's tariff comes in an official English edition and an official Japanese edition. The edition is chosen by tariff_language, never by Accept-Language: a reader who sends Accept-Language: ja gets Japanese labels and messages, and the English edition of the tariff unless the request names tariff_language ja.
  • Vietnamese text of the VN schedule keeps following the interface language, as before.
  • An integration that stores results for one team should set language explicitly on every classify request, so the stored text does not depend on the headers of whichever client created it.