Chuyển đến nội dung chính

​
Tổng quan tệp

i18n.yml kiểm soát các 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

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ữ cục bộ

  • locales.source: ngôn ngữ nguồn.
  • locales.targets: danh sách các ngôn ngữ đích.
  • tùy chọn locales.fallbacks: thứ tự dự phòng cho mỗi ngôn ngữ.

​
Xô chứa

buckets ánh xạ các tệp nguồn sang 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 đích
Sử dụng {{source}}, {{target}}, và {{localeDir}} trong các mẫu. {{localeDir}} sẽ phân giải thành một đoạn trống khi đích bằng nguồn, và thành ngôn ngữ đích trong các trường hợp khác.

​
Mẫu ánh xạ tệp CSV

Dùng ánh xạ tệp bucket để mô hình hóa quy trình CSV. Tệp theo từng ngôn ngữ: 
{
  "from": "translations/en.csv",
  "to": "translations/[locale].csv"
}
Tệp đa ngôn ngữ dùng chung: 
{
  "from": "translations/catalog.csv",
  "to": "translations/catalog.csv"
}
Đối với các tệp CSV đa ngôn ngữ dùng chung, 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 nhất quán.

​
Nhóm

groups.<name> xác định những gì sẽ được xử lý cùng nhau.
  • targets: tập con của locales.targets
  • buckets: danh sách tên bucket
groups là tùy chọn đối với 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.

​
Hồ sơ LLM

llm.profiles.<name> trường:
  • provider: openai, azure_openai, anthropic, gemini, bedrock, lmstudio, groq, mistral, hoặc ollama
  • model: mã mô hình nhà cung cấp
  • system_prompt (tùy chọn): mẫu thông báo hệ thống rõ ràng
  • user_prompt (tùy chọn): mẫu thông báo người dùng rõ ràng
  • prompt (đã ngừng dùng, tùy chọn): mẫu lời nhắc cũ được dùng làm phương án dự phòng của hệ thống
Biến nhắc:
  • {{source}}
  • {{target}}
  • {{input}}

​
Quy tắc

llm.rules chọn hồ sơ theo nhóm.
  • priority: cao hơn thắng
  • group: tên nhóm
  • profile: tên hồ sơ
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ẽ quay về llm.profiles.default.

​
Bộ nhớ đệm

cache cấu hình client bộ nhớ đệm từ xa.
  • enabled (tùy chọn): bật bộ nhớ đệm từ xa cho run.
  • endpoint (bắt buộc khi enabled=true): endpoint của dịch vụ bộ nhớ đệm từ xa.
  • project_key_env (bắt buộc khi enabled=true): tên biến môi trường chứa khóa cache 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.

​
Ví dụ nâng cao

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

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

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

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

​
Mẹo xác thực

  • Nếu bạn bỏ qua groups, mọi bucket sẽ chạy cho mọi ngôn ngữ đích.
  • 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.