How APITube handles languages and translation#

APITube automatically detects the language of every article during processing and returns it as a two-letter code in each article’s language field. Article text is always delivered in its original language, and a non-English article additionally carries an English machine translation of its headline and description in the translations.en block — enough to scan foreign coverage and decide what deserves a full read.

That makes “handling languages” in APITube three things: detection (built in, exposed on every article), filtering (you pass the language codes you want with language.code), and translation into English (precomputed, shipped alongside the original text rather than replacing it).

How does APITube detect an article’s language?#

Language detection runs while the article is being parsed, before it ever reaches the API. APITube reads the article’s title and description first — the cleanest text available — and only falls back to the full body when that text is too short. This order matters: a page body often contains navigation and footer text in English, which can make a compact detector mislabel a Chinese or Japanese article as English. Detecting from the clean title and description avoids that.

The detected value is stored as an ISO 639-1 two-letter code such as en, fr, de, ja or zh. If the language genuinely cannot be determined, the article falls back to the code un (undetermined).

Where do I see an article’s language in the response?#

Every article object carries a language field with its detected ISO 639-1 code, so you can confirm exactly what you received:

{
    "id": 123456789,
    "title": "…",
    "language": "fr"
}

The language field is part of the standard enrichment returned with every article, alongside entities, sentiment and categories. For the full set of fields, see What NLP enrichment is applied to each article?.

How do I get news in specific languages?#

Add the language.code parameter with one or more ISO 639-1 codes. This returns English and Spanish articles in a single call, ordered newest first:

curl "https://api.apitube.io/v1/news/everything?language.code=en,es&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Key rules for language.code:

• Up to three codes, separated by commas. Articles in any of those languages match (OR logic).
• Each code must be one or two characters; the value is case-insensitive, so EN and en behave the same.
• The alias us is treated as en.

To keep everything except certain languages, use ignore.language.code with the same rules:

curl "https://api.apitube.io/v1/news/everything?ignore.language.code=fr&api_key=YOUR_API_KEY"

For a deeper walkthrough of single-language, multi-language and exclusion patterns, see How to filter news by language.

Does the News API translate articles?#

Yes — the headline and the description, into English, already computed by the time you receive the article. Every article object carries a translations block:

{
    "language": "de",
    "title": "Kanzler kündigt neuen Haushalt an",
    "translations": {
        "en": {
            "title": "Chancellor announces new budget",
            "description": "The government presented the budget for the next year."
        }
    }
}

Five rules worth knowing before you build against it:

• Only the title and description are translated. The article body is not — it stays in the source language, with no English counterpart anywhere in the response.
• The block is always in the response. There is no parameter to switch translation on, and no extra cost — translations is part of the standard article shape, like sentiment or entities.
• The original text is never replaced. title and description keep the source language, and language still reports that source language. Your code decides which of the two to show.
• English articles have an empty block. Both fields are null, because the source text is already English — there is nothing to translate.
• Translation is machine translation, computed once during article processing. It is built for scale and screening, not for publication-grade copy: expect solid gist, occasional awkward phrasing in long sentences.

Translation covers 48 source languages. A language outside that set — Macedonian, for example — is still detected, filtered and delivered normally; only its translations.en fields stay null.

How do I read the English translation of a non-English article?#

Read translations.en.title and fall back to title when it is null. That one line covers both English and non-English articles:

const headline = article.translations?.en?.title ?? article.title;

If the English headline is all you need, request just those fields and skip the original bodies entirely — a much smaller response:

curl "https://api.apitube.io/v1/news/everything?language.code=de&fl=id,language,translations.en.title,translations.en.description&api_key=YOUR_API_KEY"

The translation travels through every delivery format, not only JSON: <translations> in XML, a Translations column in CSV, TSV and XLSX, a translations column in Parquet, and the full block on every line of JSONL. RSS is the one exception — its item schema carries only the original title, link and description.

Translated fields are returned in full on every plan, including Free — the only field the Free plan trims is the article body.

Which languages does APITube support?#

The canonical list of language codes accepted by language.code — and detected on incoming articles — lives in the documentation’s list of supported languages, which currently contains 60 codes. Any two-letter code from that table is valid; a code that is not on the list is rejected (see the error question below).

Common Questions#

• What does the language field contain if detection fails?
• Can I request more than three languages at once?
• What error means a language code is invalid?
• Does language.code change the language of the returned text?
• Can I search or filter by the translated text?
• Can I get translations into a language other than English?

What does the language field contain if detection fails?#

When APITube cannot determine an article’s language, the language field falls back to un (undetermined) rather than guessing. Well-covered languages are detected reliably; un is the exception, not the norm.

Can I request more than three languages at once?#

No. Both language.code and ignore.language.code accept at most three codes. If you list more, only the first three are applied and the rest are silently dropped — so language.code=en,fr,de,es behaves as en,fr,de. Keep the list to three meaningful codes.

What error means a language code is invalid?#

A code that is empty or longer than two characters returns HTTP 400 with error ER0061 (or ER0063 for the ignore.language.code variant). A well-formed two-letter code that is not in APITube’s language list returns HTTP 400 with ER0237 (ER0239 for the ignore variant) and a message like language with code 'xx' not found.

Does language.code change the language of the returned text?#

No. language.code only filters which articles come back. Each matching article is still delivered in its original language, and its language field reflects that original, detected language — the English version lives separately in translations.en and is returned whether or not you filter by language.

Can I search or filter by the translated text?#

Not yet. Keyword filters such as title match the original text, so a German article about the chancellor is found by title=Bundeskanzler, not by title=chancellor. The translation is returned for reading, not indexed for search. Two workarounds: search in the source language, or fetch a language slice with language.code and match translations.en.title yourself after retrieval.

Can I get translations into a language other than English?#

No. English is the only target language today. The response shape already allows for more — translations is keyed by language code, so translations.en would sit next to any future target — but only the en key is populated.