import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/vi/functional-basic/Classes/Translate - Quản lý Bản dịch và Văn bản'/>

# Lớp Translate

Một lớp bao tĩnh (static wrapper) cho một thực thể mặc định của lớp `TranslateInstance`. Nó quản lý bản dịch và văn bản đa ngôn ngữ ở cấp độ toàn cục, cung cấp các công cụ để truy xuất, lưu trữ bộ nhớ đệm (cache) và hiển thị nội dung với hỗ trợ mẫu (template) cùng khả năng tự động phát hiện ngôn ngữ.

## Mối liên hệ với TranslateInstance

Lớp `Translate` hoạt động như một giao diện toàn cục, được cấu hình sẵn cho `TranslateInstance`. Tất cả các phương thức tĩnh đều gọi đến các phương thức tương ứng trên một thực thể nội bộ (`Translate.getItem()`).

Mặc dù `Translate` phù hợp cho hầu hết các nhu cầu dịch thuật toàn ứng dụng, bạn có thể tạo các môi trường dịch thuật độc lập bằng cách sử dụng `TranslateInstance`.

## Tính năng chính

- **Tải theo lô (Batch Loading)** — Tự động gom nhóm các yêu cầu dịch thuật và gửi đi trong một gói duy nhất sau 160ms kể từ khi đưa vào hàng đợi.
- **Mẫu văn bản linh hoạt** — Hỗ trợ thay thế tham số trong văn bản thông qua chỉ số (`[0]`) hoặc khóa định danh (`{key}`).
- **Truy cập Đồng bộ và Bất đồng bộ** — Cung cấp các phương thức lấy văn bản tức thì từ cache (`getSync`) hoặc đảm bảo tải từ máy chủ (`get`).
- **Bộ nhớ đệm thông minh** — Lưu trữ bản dịch theo mã vùng hiện tại và hỗ trợ cơ chế dự phòng (Vị trí > Ngôn ngữ > Toàn cầu).

## Khởi tạo

Lớp này là tĩnh và không yêu cầu khởi tạo đối tượng. Cấu hình được áp dụng cho thực thể dịch thuật toàn cục.

```javascript
import { Translate } from '@dxtmisha/functional-basic'

// Cấu hình URL API cho thực thể toàn cục
Translate.setUrl('/api/v1/translate')

// Tải trước các văn bản cần thiết
await Translate.add(['welcome', 'auth.login'])
```

## Phương thức

### Cấu hình

- `setConfig(config: TranslateConfig): Translate` — Thiết lập cấu hình hoàn chỉnh cho thực thể dịch thuật.
- `setUrl(url: string): Translate` — Thay đổi đường dẫn API để lấy bản dịch.
- `setPropsName(name: string): Translate` — Thay đổi tên thuộc tính được sử dụng trong yêu cầu/phản hồi API.
- `setReadApi(value: boolean): Translate` — Bật hoặc tắt việc lấy bản dịch từ API.

### Truy xuất bản dịch

- `async get(name: string, replacement?: any): Promise<string>` — Lấy văn bản bất đồng bộ. Nếu không có trong cache và không phải môi trường localhost, hệ thống sẽ cố gắng tải từ máy chủ.
- `getSync(name: string, first?: boolean, replacement?: any): string` — Trả về văn bản từ cache. Nếu `first` là `true`, trả về một khoảng trắng ` ` nếu thiếu văn bản.
- `async getList<T>(names: T): Promise<TranslateList<T>>` — Lấy một nhóm các bản dịch (bất đồng bộ).
- `getListSync<T>(names: T, first?: boolean): TranslateList<T>` — Lấy một nhóm các bản dịch từ cache (đồng bộ).

### Cập nhật theo lô

- `async add(names: string | string[]): Promise<void>` — Thêm nhiều mã vào hàng đợi để tải theo lô.
- `addSync(data: Record<string, string>): void` — Thêm trực tiếp các bản dịch vào bộ nhớ đệm.
- `async addNormalOrSync(data: Record<string, string>): Promise<void>` — Thêm bản dịch trực tiếp trên localhost, ngược lại sẽ đưa vào hàng đợi để tải.
- `addSyncByLocation(data: Record<string, Record<string, string>>): void` — Thêm bản dịch cho các vị trí/ngôn ngữ cụ thể.
- `addSyncByFile(data: TranslateDataFile): void` — Thêm bản dịch từ định nghĩa tệp.

### Static và Thực thể (Instance)

- **Cách dùng**: Truy cập toàn cục bằng `Translate` ở bất kỳ đâu trong ứng dụng hoặc sử dụng `TranslateInstance` cho các thực thể độc lập, theo từng khu vực cụ thể.
- **Trạng thái**: Trạng thái `Translate` chia sẻ chung cho toàn bộ ứng dụng, trong khi `TranslateInstance` cung cấp trạng thái cô lập cho các thành phần hoặc mô-đun cụ thể.
- **Khởi tạo**: `Translate` không yêu cầu khởi tạo đối tượng (lớp bao tĩnh), trong khi `TranslateInstance` được tạo thông qua `new TranslateInstance()`.

## Các thực thể độc lập

Nếu bạn cần quản lý một tập hợp các bản dịch riêng biệt (ví dụ: cho một ứng dụng con cụ thể hoặc một widget chuyên dụng), hãy sử dụng `TranslateInstance` thay vì lớp `Translate` toàn cục.

```javascript
import { TranslateInstance, TranslateFile } from '@dxtmisha/functional-basic'

// 1. Tạo một bộ tệp dịch chuyên dụng
const widgetFiles = new TranslateFile({
  'vi-VN': () => import('./locales/widget.vi-VN.json')
})

// 2. Khởi tạo một thực thể dịch thuật độc lập
const widgetTranslate = new TranslateInstance(
  '/api/widget/translate', 
  'list', 
  widgetFiles
)

// 3. Sử dụng độc lập
const label = await widgetTranslate.get('widget.welcome')
```

## Kiểu dữ liệu (Types)

### `TranslateCode`
Một chuỗi (mã văn bản) hoặc một mảng các chuỗi. Mảng được dùng để thay thế mẫu (template):
- `string` — ví dụ: `'welcome'`
- `string[]` — ví dụ: `['welcome', 'Khách']`

### `TranslateList`
Một bản ghi (record) với khóa là mã bản dịch và giá trị là các chuỗi đã dịch tương ứng.

## Ví dụ

### Làm việc với mẫu (Template)
```javascript
// Trong cơ sở dữ liệu: "Xin chào, [0]! Bạn có {count} thông báo."
const text = await Translate.get('user.notifications', ['Sơn', { count: 5 }])
// Kết quả: "Xin chào, Sơn! Bạn có 5 thông báo."
```

### Lấy danh sách hàng loạt
```javascript
const labels = await Translate.getList([
  'home.title',
  ['home.welcome', 'Khách'], 
  'home.footer'
])
```
