> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# cấu hình i18n

> Hướng dẫn từng trường cho tệp cấu hình i18n được dùng bởi các lệnh run, status và sync.

## Tổng quan tệp

`i18n.yml` điều khiển ngôn ngữ, ánh xạ tệp, hồ sơ mô hình và định tuyến nâng cao tùy chọn. `i18n.jsonc` vẫn được hỗ trợ để tương thích.

## Cấu hình khởi đầu

```yaml theme={null}
locales:
  source: en-US
  targets:
    - es-ES

buckets:
  ui:
    files:
      - from: packages/ui/lang/{{source}}.json
        to: apps/web/lang/{{target}}.json

llm:
  profiles:
    default:
      provider: openai
      model: gpt-5.2
```

Đây là hình dạng được viết bởi `hyperlocalise init`.

Khi `groups` bị bỏ qua, Hyperlocalise sẽ tự động sử dụng một nhóm `default` ngầm định với:

* tất cả các ngôn ngữ từ `locales.targets`
* tất cả tên bucket từ `buckets`

## Ngôn ngữ vùng miền

* `locales.source`: ngôn ngữ nguồn.
* `locales.targets`: danh sách ngôn ngữ đích.
* tùy chọn `locales.fallbacks`: thứ tự dự phòng theo từng ngôn ngữ.

## Xô chứa

`buckets` ánh xạ các tệp nguồn tới các mẫu đầu ra đích.

Mỗi ánh xạ tệp sử dụng:

* `from`: mẫu đường dẫn nguồn
* `to`: mẫu đường dẫn mục tiêu

Sử dụng `{{source}}`, `{{target}}`, và `{{localeDir}}` trong các mẫu. `{{localeDir}}` được phân giải thành một phân đoạn trống khi đích bằng nguồn, và thành ngôn ngữ của đích trong các trường hợp khác.

### Các mẫu ánh xạ locale của mảng PHP

Các mảng locale kiểu Laravel có thể được ánh xạ trực tiếp khi mỗi tệp trả về một mảng PHP tĩnh duy nhất.

```yaml theme={null}
buckets:
  app:
    files:
      - from: resources/lang/en/messages.php
        to: resources/lang/{{target}}/messages.php
      - from: resources/lang/en/validation.php
        to: resources/lang/{{target}}/validation.php
```

Các tệp ngôn ngữ PHP được hỗ trợ phải bắt đầu bằng `<?php` và trả về một literal tĩnh `[...]` hoặc `array(...)`. Hyperlocalise dịch các chuỗi lá, làm phẳng các khóa lồng nhau bằng đường dẫn có dấu chấm, và giữ nguyên chú thích, thứ tự cũng như cú pháp mảng khi ghi. PHP động như biến, lời gọi hàm, hằng số, `declare(...)`, hoặc các chuỗi được nội suy trong dấu ngoặc kép kép đều bị từ chối một cách có chủ ý.

Các phần mở rộng tệp ngôn ngữ được hỗ trợ bao gồm `.json`, `.jsonc`, `.yaml`, `.yml`, `.php`, `.xml`, `.resx`, `.arb`, `.xlf`, `.xlif`, `.xliff`, `.po`, `.html`, `.liquid`, `.md`, `.mdx`, `.strings`, `.stringsdict`, và `.csv`.

Các tệp ngôn ngữ YAML/YML nên là các tệp có dạng ánh xạ với các lá là chuỗi. Các ánh xạ lồng nhau sẽ trở thành các khóa dạng chấm, các chuỗi sẽ trở thành các khóa `[index]`, và writeback sẽ ghi lại các lá chuỗi hiện có trong khi vẫn giữ nguyên thứ tự khóa/chú thích nếu có thể. Các khóa ánh xạ không được chứa `.`, `[`, hoặc `]` vì các ký tự đó được dành riêng cho các đường dẫn đã được làm phẳng. Các lá vô hướng không phải chuỗi như số, giá trị boolean, null, dấu thời gian, anchor và alias sẽ bị từ chối để tránh làm hỏng siêu dữ liệu một cách âm thầm.

```yaml theme={null}
buckets:
  ui:
    files:
      - from: packages/ui/lang/{{source}}.yaml
        to: apps/web/lang/{{target}}.yaml
```

Các ánh xạ XML chung có thể trỏ tới các tệp locale XML không phải Android:

```yaml theme={null}
buckets:
  xml:
    files:
      - from: locales/en-US.xml
        to: locales/[locale].xml
```

Các mục XML phải là các phần tử lá chỉ chứa văn bản, được định danh bằng `key`, `id`, hoặc `name`, hoặc là các lá theo đường dẫn lồng nhau. Các tệp `<resources>` của Android, XML có nội dung hỗn hợp, và ghi trả lại giữ nguyên CDATA không được trình phân tích cú pháp XML tổng quát xử lý.

### Các mẫu ánh xạ tệp CSV

Dùng ánh xạ tệp bucket để mô hình hóa các quy trình làm việc CSV.

Các tệp theo từng ngôn ngữ:

```json theme={null}
{
  "from": "translations/en.csv",
  "to": "translations/[locale].csv"
}
```

Tệp đa ngôn ngữ dùng chung:

```json theme={null}
{
  "from": "translations/catalog.csv",
  "to": "translations/catalog.csv"
}
```

Đối với các tệp CSV đa ngôn ngữ được chia sẻ, hãy giữ một cột khóa và một cột ngôn ngữ đích mà `run` có thể cập nhật một cách nhất quán.

### Các mẫu ánh xạ tệp Fluent

Sử dụng các ánh xạ `.ftl` cho các tệp ngôn ngữ Mozilla Fluent:

```json theme={null}
{
  "from": "locales/en-US/messages.ftl",
  "to": "locales/[locale]/messages.ftl"
}
```

Hyperlocalise hỗ trợ các thông điệp Fluent, thuộc tính, giá trị nhiều dòng và các giá trị select/plural như các đơn vị dịch hoàn chỉnh. Thuộc tính sử dụng các khóa có dấu chấm như `brand.title`. Các term Fluent không được hỗ trợ và sẽ bị lỗi khi phân tích cú pháp.

### Mẫu mô-đun ngôn ngữ JS/TS

Sử dụng các ánh xạ mô-đun locale của JavaScript hoặc TypeScript khi ứng dụng của bạn nhập trực tiếp các đối tượng locale:

```yaml theme={null}
buckets:
  web:
    files:
      - from: apps/web/messages/{{source}}.ts
        to: apps/web/messages/{{target}}.ts
```

Các mô-đun được hỗ trợ phải xuất một đối tượng tĩnh, ví dụ:

```ts theme={null}
export default {
  home: {
    title: "Welcome",
    cta: "Start now",
  },
} as const;
```

Hyperlocalise bảo toàn các chú thích, import, cú pháp export và văn bản mô-đun không phải thông điệp. Nó từ chối các giá trị động, khóa tính toán, thuộc tính spread, nhiều đối tượng ngôn ngữ được export, và các template literal được nội suy.

### Các mẫu ánh xạ catalog chuỗi của Apple

Sử dụng các ánh xạ `.xcstrings` cho các string catalog của Xcode:

```json theme={null}
{
  "from": "ios/en.lproj/Localizable.xcstrings",
  "to": "ios/[locale].lproj/Localizable.xcstrings"
}
```

Hyperlocalise ghi các giá trị đích vào `localizations[targetLocale]` và bảo toàn siêu dữ liệu của danh mục. `status` và `check` đọc ngôn ngữ miền địa phương đích được yêu cầu từ danh mục. Các mục nguồn của biến thể và thay thế phải bao gồm bản địa hóa bằng ngôn ngữ nguồn để Hyperlocalise có thể trích xuất các dạng nguồn một cách an toàn.

### Ánh xạ chuỗi tài nguyên XML của Android

Hỗ trợ XML của Android được cố ý giới hạn trong các tệp tài nguyên chuỗi có tên `strings.xml` trong các thư mục `res/values*`. Sử dụng tên định danh ngôn ngữ Android trong đường dẫn đích của bạn:

```yaml theme={null}
buckets:
  android:
    files:
      - from: app/src/main/res/values/strings.xml
        to: app/src/main/res/values-{{target}}/strings.xml
```

Các mục tài nguyên được hỗ trợ là `<string name="...">` và `<plurals name="..."><item quantity="...">`. Các tài nguyên được đánh dấu `translatable="false"` sẽ được giữ nguyên và bỏ qua. Các dạng tài nguyên có thể dịch không được hỗ trợ như `<string-array>` sẽ lỗi theo cơ chế fail closed, vì vậy chúng không bị loại bỏ âm thầm.

### Các mẫu ánh xạ của tệp thuộc tính Java

Sử dụng các ánh xạ `.properties` cho các gói tài nguyên Java với một tệp cho mỗi locale:

```yaml theme={null}
buckets:
  java:
    files:
      - from: src/main/resources/messages_{{source}}.properties
        to: src/main/resources/messages_{{target}}.properties
```

Các mục được hỗ trợ là các khóa thuộc tính Java phẳng với giá trị chuỗi. Hyperlocalise bảo toàn chú thích, dấu phân tách và thứ tự khóa khi ghi; các giá trị đã dịch được ghi dưới dạng giá trị một dòng được thoát `.properties`.

## Quy tắc

`llm.rules` chọn hồ sơ cho mỗi nhóm.

* `priority`: giá trị cao hơn thắng
* `group`: tên nhóm

`llm.rules` là tùy chọn. Khi không có quy tắc nào khớp với một nhóm, Hyperlocalise sẽ chuyển sang `llm.profiles.default`.

## Bộ nhớ đệm

`cache` cấu hình ứng dụng khách bộ nhớ đệm từ xa.

* `enabled` (tùy chọn): bật bộ nhớ đệm từ xa cho `run`.
* `endpoint` (không bắt buộc trừ khi `enabled=true`): điểm cuối dịch vụ bộ nhớ đệm từ xa.
* `project_key_env` (tùy chọn trừ khi `enabled=true`): biến môi trường chứa khóa bộ nhớ đệm của dự án.
* `timeout_seconds` (tùy chọn): thời gian chờ yêu cầu bộ nhớ đệm từ xa tính bằng giây.
* Nếu bạn bỏ qua `groups`, mọi bucket sẽ chạy cho mọi locale đích.

Biến nhắc:

* `{{source}}`
* `{{target}}`
* `{{input}}`

## Ví dụ nâng cao

Sau đó chỉnh sửa `i18n.yml` đã được tạo cho dự án của bạn.

* Giữ các mục tiêu nhóm bên trong `locales.targets`.
* Giữ các bucket nhóm được căn chỉnh với các khóa `buckets`.
* Giữ tên hồ sơ nhất quán giữa `profiles` và `rules`.

`llm.profiles.<name>` trường:

## Tạo một mẫu khởi đầu

`groups` là tùy chọn cho các cấu hình dành cho người mới bắt đầu. Thêm nó khi bạn muốn tách việc thực thi theo locale hoặc theo bộ tệp.

* Dùng `hyperlocalise` cho các công việc `sync push` và `sync pull`.
* Giữ `storage` cho cấu hình bộ điều hợp TMS dành riêng cho nhà cung cấp.
* `profile`: tên hồ sơ
* `prompt` (lỗi thời, không bắt buộc): mẫu lời nhắc cũ được dùng làm phương án dự phòng của hệ thống

## Mẹo xác thực

```yaml theme={null}
locales:
  source: en-US
  targets:
    - fr-FR
    - es-ES
  fallbacks:
    fr-FR:
      - es-ES
      - en-US

buckets:
  ui:
    files:
      - from: packages/ui/lang/{{source}}.json
        to: apps/web/lang/{{target}}.json
  docs:
    files:
      - from: docs/{{source}}/**/*.mdx
        to: docs/{{target}}/**/*.mdx

groups:
  app:
    targets:
      - fr-FR
      - es-ES
    buckets:
      - ui
  docs:
    targets:
      - fr-FR
    buckets:
      - docs

llm:
  profiles:
    default:
      provider: openai
      model: gpt-5.2
    docs_review:
      provider: openai
      model: gpt-5.2
      system_prompt: You are a senior technical translator.
      user_prompt: |-
        Translate from {{source}} to {{target}}.

        Keep Markdown and MDX syntax intact.

        {{input}}
  context_memory:
    provider: openai
    model: gpt-5.2
  rules:
    - priority: 100
      group: docs
      profile: docs_review

hyperlocalise:
  project_id: project_123
  api_base_url: https://hyperlocalise.com/api
  api_key_env: HYPERLOCALISE_API_KEY
  manifest_path: .hyperlocalise/jobs.json
  timeout_seconds: 1200

cache:
  enabled: true
  endpoint: dns:///cache.internal:443
  project_key_env: HYPERLOCALISE_CACHE_PROJECT_KEY
  timeout_seconds: 5
```

## các hồ sơ LLM

```bash theme={null}
hyperlocalise init
```

`groups.<name>` xác định những gì cần xử lý cùng nhau.

## Các nhóm

* `user_prompt` (tùy chọn): mẫu thông điệp người dùng rõ ràng
* `system_prompt` (tùy chọn): mẫu thông báo hệ thống rõ ràng
* `model`: mã mô hình nhà cung cấp
* `provider`: `openai`, `azure_openai`, `anthropic`, `gemini`, `bedrock`, `lmstudio`, `groq`, `mistral`, hoặc `ollama`
* `buckets`: danh sách tên bucket
* `targets`: tập con của `locales.targets`