# Hỗ trợ ngôn ngữ

AstroWay đang xây dựng một **API đa ngôn ngữ** — các diễn giải văn bản, báo cáo và tử vi hằng ngày đều có sẵn bằng ngôn ngữ của người dùng. Danh sách công khai gồm 20 ngôn ngữ, được chọn dựa trên nghiên cứu nhu cầu của thị trường chiêm tinh (khối lượng tìm kiếm, mức độ phủ của đối thủ cạnh tranh, tiềm năng doanh thu).

<Aside type="tip">
**Cách hoạt động.** Truyền ngôn ngữ qua trường `language` trong phần thân của yêu cầu — hoặc `?lang=<code>` trong URL, hoặc header `Accept-Language` — đến `/v1/interpret/*`, `/v1/horoscope/*`, `/v1/reports/*`. Nếu ngôn ngữ đang hoạt động, văn bản sẽ được trả về bằng ngôn ngữ đó (các ngôn ngữ Beta có thể có sai sót ở những thuật ngữ phức tạp, kèm fallback sang tiếng Anh). Nếu ngôn ngữ không hoạt động, `/horoscope/*` và `/reports/*` (enum nghiêm ngặt) trả về `400 INVALID_INPUT`, còn `/interpret/*` thì fallback về tiếng Anh.
</Aside>

## Tình trạng hiện tại

Mỗi ngôn ngữ mang một **Status** bản dịch cùng với một **Demand score** trong roadmap (mức độ ưu tiên, 48–95+).

| # | Code | Ngôn ngữ | Status | Demand | Reports | Site |
|---|------|----------|--------|--------|---------|------|
| 1  | `uk` | Tiếng Ukraina | ✅ Source | — | ✅ | ✅ |
| 2  | `en` | Tiếng Anh | ✅ Reference | **95+** | ✅ | ✅ |
| 3  | `de` | Tiếng Đức | 🚧 Auto | 72 | 📋 | ✅ |
| 4  | `pl` | Tiếng Ba Lan | 🚧 Auto | 64 | 📋 | ✅ |
| 5  | `es` | Tiếng Tây Ban Nha | 🚧 Auto | **88** | 📋 | ✅ |
| 6  | `pt` | Tiếng Bồ Đào Nha | 🚧 Auto | **84** | 📋 | ✅ |
| 7  | `hi` | Tiếng Hindi | 🚧 Auto | **81** | 📋 | ✅ |
| 8  | `fr` | Tiếng Pháp | 🚧 Auto | **78** | 📋 | ✅ |
| 9  | `ko` | Tiếng Hàn | 🚧 Auto | **77** | 📋 | ✅ |
| 10 | `it` | Tiếng Ý | 🚧 Auto | 73 | 📋 | ✅ |
| 11 | `ja` | Tiếng Nhật | 🚧 Auto | 67 | 📋 | ✅ |
| 12 | `id` | Tiếng Indonesia | 🚧 Auto | 62 | 📋 | ✅ |
| 13 | `tr` | Tiếng Thổ Nhĩ Kỳ | 🚧 Auto | 60 | 📋 | ✅ |
| 14 | `nl` | Tiếng Hà Lan | 🚧 Auto | 58 | 📋 | ✅ |
| 15 | `cs` | Tiếng Séc | 🚧 Auto | 56 | 📋 | ✅ |
| 16 | `ro` | Tiếng Romania | 🚧 Auto | 54 | 📋 | ✅ |
| 17 | `vi` | Tiếng Việt | 🚧 Auto | 53 | 📋 | ✅ |
| 18 | `ar` | Tiếng Ả Rập | 🚧 Auto | 52 | 📋 | ✅ |
| 19 | `el` | Tiếng Hy Lạp | 🚧 Auto | 50 | 📋 | ✅ |
| 20 | `hu` | Tiếng Hungary | 🚧 Auto | 48 | 📋 | ✅ |

**Legend:**
- **Status** — ✅ Source / Reference = do con người biên soạn và duy trì (uk, en); 🚧 Auto = được dịch tự động dựa trên một bộ thuật ngữ chung, hoàn thiện dần theo thời gian (chưa có rà soát thủ công theo từng chuỗi, nên các thuật ngữ tinh tế có thể đọc còn thô; fallback sang tiếng Anh đối với bất kỳ chuỗi nào bị thiếu).
- **Site** — ✅ đã phát hành (UI + docs) · 📋 đang lên kế hoạch.
- **Reports** — ✅ đã phát hành · 📋 đang lên kế hoạch.

## Cách tạo ra các bản dịch

Tiếng Ukraina là ngôn ngữ nguồn và tiếng Anh là bản tham chiếu được duy trì — cả hai đều do con người biên soạn. Mọi ngôn ngữ khác đều được dịch tự động dựa trên một bộ thuật ngữ chiêm tinh chung (~800 mục) và hoàn thiện dần theo thời gian; chưa có rà soát thủ công theo từng chuỗi, vì vậy hãy xem chúng là Beta đối với thuật ngữ phức tạp, kèm fallback sang tiếng Anh ở nơi một chuỗi bị thiếu. Giao diện trang web và tài liệu hiện được phủ trên tất cả các ngôn ngữ được liệt kê; báo cáo PDF bản địa hóa hiện được phát hành bằng tiếng Ukraina và tiếng Anh, và sẽ mở rộng sang các ngôn ngữ còn lại theo nhu cầu.

## Demand Score — cách tính

Một chỉ số tổng hợp được xây dựng từ:
- Khối lượng Google Trends trong 12 tháng đối với các từ khóa chiêm tinh tại quốc gia đó
- Mức độ phủ của top-5 đối thủ cạnh tranh (Co–Star, AstroSeek, Astro.com, Prokerala, DivineAPI)
- Dân số ước tính × mức độ thâm nhập của ứng dụng trả phí ước tính
- Chênh lệch doanh thu trên mỗi người dùng (đã điều chỉnh theo PPP)

Đây không phải một thước đo chính xác — mà là một **thứ tự ưu tiên xếp hạng** giúp quyết định "tiếp theo là gì" một cách khách quan thay vì theo cảm tính.

## Cách gọi

```bash
curl -X POST https://api.astroway.info/v1/interpret/aspects \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "language": "es",
    "aspects": [
      { "body1": "Sun", "body2": "Moon", "type": "conjunction", "orb": 2.1 }
    ]
  }'
```

Phản hồi (ví dụ cho `language=es`):

```json
{
  "ok": true,
  "data": {
    "interpretation": "El aspecto Sol-Luna en conjunción simboliza...",
    "language": "es"
  }
}
```

Trường `language` trong phản hồi lặp lại ngôn ngữ đã được áp dụng (tiện làm chỉ báo UX). Trạng thái chất lượng bản dịch nằm trong bảng phía trên; phản hồi của API **không** trả về thông tin này.

## Nếu bạn cần một ngôn ngữ không có trong danh sách

Hãy gửi email đến [hello@astroway.info](mailto:hello@astroway.info) kèm bằng chứng về nhu cầu (người dùng mẫu, khối lượng dự kiến). Chúng tôi rà soát danh sách **hằng quý** — một ngôn ngữ có nhu cầu thực tế từ bên ngoài có thể được bổ sung làm Tier 4 (opt-in).

Một số ngôn ngữ trong danh sách rút gọn bị **loại trừ vĩnh viễn** — `da, fi, no, bg, sk, hr, zh-CN, fa, tl` — do thị trường nhỏ hoặc không có truyền thống chiêm tinh. Chúng không hoạt động: `/horoscope/*` và `/reports/*` trả về `400 INVALID_INPUT`, còn `/interpret/*` thì fallback về tiếng Anh.

## Liên quan

- [Độ chính xác của tính toán](/vi/accuracy/) — các phép tính số học là **độc lập với ngôn ngữ**, chỉ có văn bản được bản địa hóa
- [Báo cáo](/vi/products/) — báo cáo PDF đa ngôn ngữ
- [Idempotency](/vi/idempotency/) — ưu đãi cache hoạt động độc lập với `lang`