# Astrology API localization, one parameter for every language

> Add `?lang=` to any RoxyAPI call and the reading comes back in that language. Ten languages, native script, the same fields. Interpretations, keywords, and reference cards translate; the identifiers your code reads stay English, so one integration serves every market.

RoxyAPI writes the interpretation text for you, and it writes it in ten languages. You do not run a translation pipeline, maintain locale files, or call a separate service. You pass one query parameter and the horoscope, tarot reading, or Vedic chart comes back ready to show a reader in their own language.

## Add `?lang=` to any call

Every translated endpoint accepts a `lang` query parameter. Leave it off and you get English. Set it and the display copy comes back in that language.


### curl
```bash
curl "https://roxyapi.com/api/v2/tarot/cards/fool?lang=fr" \
  -H "X-API-Key: YOUR_KEY"
```

### JavaScript
```js
const res = await fetch(
  'https://roxyapi.com/api/v2/tarot/cards/fool?lang=fr',
  { headers: { 'X-API-Key': 'YOUR_KEY' } }
);
const card = await res.json();
// card.name === "Le Mat"
```

### Python
```python
import requests
r = requests.get(
    'https://roxyapi.com/api/v2/tarot/cards/fool',
    params={'lang': 'fr'},
    headers={'X-API-Key': 'YOUR_KEY'},
)
card = r.json()  # card["name"] == "Le Mat"
```

The same card returns `El Loco` in Spanish, `Der Narr` in German, `मूर्ख` in Hindi, and `Шут` in Russian, each with the full description rather than a shortened stub.

## Supported languages

Pass any of these codes as `?lang=`. The list is also served live from `GET /api/v2/languages`.

| Code | Language | Native name |
|------|----------|-------------|
| `en` | English | English |
| `tr` | Turkish | Türkçe |
| `de` | German | Deutsch |
| `es` | Spanish | Español |
| `hi` | Hindi | हिन्दी |
| `pt` | Portuguese | Português |
| `fr` | French | Français |
| `ru` | Russian | Русский |
| `zh-Hans` | Chinese (Simplified) | 简体中文 |
| `zh-Hant` | Chinese (Traditional) | 繁體中文 |

Simplified and Traditional Chinese are available today on the Chinese astrology and Feng Shui domains. Every other language is available across the full catalog.

**Tip: Fetch `GET /api/v2/languages` once when you build a language picker. Each entry carries the `code` you send and the `nativeName` you display, so the list never has to be hardcoded in your app.**

## What translates, and what stays English

This is the one rule worth internalizing before you build a multi-language app: the words a reader sees translate, and the values your code reads do not.

- **Display copy translates.** Descriptions, summaries, keywords, and reference cards come back in the language you requested.
- **Identifiers stay English.** A planet name, a sign, an aspect `type`, an `interpretation` of `harmonious` or `challenging`: these are values your code compares or switches on, so they are the same string in every language. Write `if (aspect.interpretation === 'challenging')` once and it holds in all ten.
- **Where you need both, the translated word arrives as a `...Localized` sibling field.** It is absent under `?lang=en`, so a plain English call is byte-identical to one made before the field existed.

```json
{
  "type": "TRINE",
  "typeLocalized": "Trígono",
  "interpretation": "harmonious"
}
```

Print `typeLocalized ?? type`, and branch on `type`. The full field contract, with more examples, is in [own your voice](/docs/guides/calculation-engine "structured fields, the identifier contract, and building your own interpretation layer").

## When a language is not available

Two honest behaviors, both easy to handle:

- **An unsupported code is rejected.** `?lang=xx` returns `400`, so a typo fails loudly instead of quietly serving the wrong language. Validate against the `/languages` list, or send a code straight from the table above.
- **A domain without a given language returns English for those fields.** Where a translation is not yet published for a specific domain, that field reads in English rather than coming back blank. A call is never broken by being early to a language.

## Frequently asked questions

**Which languages does the astrology API support?**

Ten: English, Turkish, German, Spanish, Hindi, Portuguese, French, Russian, and both Simplified and Traditional Chinese. Send the code (like `es` or `zh-Hant`) as the `lang` query parameter on any call. The live list is served from `GET /api/v2/languages`.

**How do I get a horoscope or reading in Spanish?**

Add `?lang=es` to the request. `GET /api/v2/tarot/cards/fool?lang=es` returns the card as `El Loco` with its Spanish description. The same parameter works on horoscopes, natal charts, numerology, and every translated endpoint.

**Do the field names or values change when I translate?**

Field names never change, and the identifiers your code reads (planet names, signs, aspect types) stay English in every language, so your logic keeps working. Only the human-readable copy translates, and where you also need the translated word it arrives as a `...Localized` field beside the English one.

**What happens if I request a language you do not support?**

The call returns a `400` error. An unsupported or misspelled code fails immediately rather than silently defaulting, so you catch it in development. Validate the code against `GET /api/v2/languages` when you accept a language from user input.

## Next steps

Build your own voice on top of the translated data in [own your voice](/docs/guides/calculation-engine "own your interpretation layer while launching on ready readings"), cut repeat calls with [caching](/docs/guides/caching "which calculations are safe to cache and how to key them"), and browse every endpoint in the [product catalog](/products "all domains and endpoints on one key").