跳转到主要内容

​
文件概览

i18n.yml 控制区域设置、文件映射、模型配置文件以及可选的高级路由。i18n.jsonc 仍受支持以保持兼容性。

​
入门配置

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
这是由 hyperlocalise init 写下的形状。 当省略 groups 时，Hyperlocalise 会自动使用一个隐式的 default 组，包含：
  • 所有语言环境来自locales.targets
  • 所有存储桶名称来自buckets

​
区域设置

  • locales.source：源语言环境。
  • locales.targets：目标语言环境列表。
  • 可选 locales.fallbacks：每个区域设置的回退顺序。

​
分组

buckets 将源文件映射到目标输出模板。 每个文件映射使用：
  • from：源路径模板
  • to：目标路径模板
在模板中使用 {{source}}、{{target}} 和 {{localeDir}}。当目标等于源时，{{localeDir}} 会解析为空片段，否则解析为目标区域设置。

​
CSV 文件映射模式

使用 bucket 文件映射来建模 CSV 工作流。 每个语言环境的文件： 
{
  "from": "translations/en.csv",
  "to": "translations/[locale].csv"
}
共享多语言文件： 
{
  "from": "translations/catalog.csv",
  "to": "translations/catalog.csv"
}
对于共享的多语言 CSV 文件，请保留一个键列和一个目标语言列，以便 run 能够一致地更新。

​
组

groups.<name> 定义了要一起处理的内容。
  • targets：locales.targets的子集
  • buckets：存储桶名称列表
groups 对初学者配置是可选的。 当你想按语言区域或文件集拆分执行时，请添加它。

​
LLM 配置文件

llm.profiles.<name> 字段:
  • provider：openai、azure_openai、anthropic、gemini、bedrock、lmstudio、groq、mistral，或 ollama
  • model：提供方模型 ID
  • system_prompt（可选）：显式系统消息模板
  • user_prompt（可选）：显式用户消息模板
  • prompt（已弃用，可选）：用作系统回退的旧版提示模板
提示变量：
  • {{source}}
  • {{target}}
  • {{input}}

​
规则

llm.rules 按组选择配置文件。
  • priority：更高者获胜
  • group：组名
  • profile：配置文件名称
llm.rules 是可选的。当没有规则匹配某个组时，Hyperlocalise 会回退到 llm.profiles.default。

​
缓存

cache 配置远程缓存客户端。
  • enabled（可选）：为 run 启用远程缓存。
  • endpoint（当 enabled=true 时必填）：远程缓存服务端点。
  • project_key_env（当 enabled=true 时必填）：保存项目缓存密钥的环境变量名。
  • timeout_seconds（可选）：远程缓存请求超时时间（秒）。

​
高级示例

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

​
生成一个起始模板

hyperlocalise init
然后为你的项目编辑生成的i18n.yml。

​
验证提示

  • 如果你省略groups，则每个存储桶都会针对每个目标区域设置运行。
  • 将组目标保留在locales.targets内。
  • 保持组桶与 buckets 键对齐。
  • 在 profiles 和 rules 之间保持个人资料名称一致。