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

# i18n 配置

> run、status 和 sync 命令使用的 i18n 配置文件字段逐项指南。

## 文件概览

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

## 入门配置

```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
```

这是由`hyperlocalise init`写下的形状。

当省略 `groups` 时，Hyperlocalise 会自动使用一个隐式的 `default` 组，包含：

* 所有区域设置，来自`locales.targets`
* 所有来自 `buckets` 的桶名称

## 语言环境

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

## 存储桶

`buckets` 将源文件映射到目标输出模板。

每个文件映射使用：

* `from`：源路径模板
* `to`：目标路径模板

在模板中使用 `{{source}}`、`{{target}}` 和 `{{localeDir}}`。当目标等于源时，`{{localeDir}}` 会解析为空片段；否则会解析为目标区域设置。

### PHP 数组区域设置映射模式

当每个文件返回一个静态的 PHP 数组时，Laravel 风格的区域设置数组可以直接映射。

```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
```

受支持的 PHP 区域设置文件必须以 `<?php` 开头，并返回静态的 `[...]` 或 `array(...)` 字面量。Hyperlocalise 会翻译字符串叶子节点，将嵌套键展平成带点路径，并在写入时保留注释、顺序和数组语法。像变量、函数调用、常量、`declare(...)` 或插值的双引号字符串等动态 PHP 会被有意拒绝。

支持的区域设置文件扩展名包括`.json`、`.jsonc`、`.yaml`、`.yml`、`.php`、`.xml`、`.resx`、`.arb`、`.xlf`、`.xlif`、`.xliff`、`.po`、`.html`、`.liquid`、`.md`、`.mdx`、`.strings`、`.stringsdict`和`.csv`。

YAML/YML 区域设置文件应为映射结构的文件，且叶子节点为字符串。嵌套映射会变成点分键，序列会变成 `[index]` 键，而写回会在尽可能保留键顺序/注释的同时重写现有字符串叶子节点。映射键不能包含 `.`、`[` 或 `]`，因为这些字符保留用于展平后的路径。为避免静默损坏元数据，会拒绝非字符串标量叶子节点，例如数字、布尔值、空值、时间戳、锚点和别名。

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

通用 XML 映射可以指向非 Android 的 XML 区域设置文件：

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

XML 条目必须是仅文本的叶子元素，并以 `key`、`id` 或 `name` 为键，或者是嵌套的路径形叶子。Android `<resources>` 文件、混合内容 XML，以及保留 CDATA 的回写，通用 XML 解析器都不处理。

### CSV 文件映射模式

使用存储桶文件映射来建模 CSV 工作流。

按语言区域的文件：

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

共享多语言文件：

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

对于共享的多语言 CSV 文件，请保留一个键列和一个目标语言列，这样 `run` 就可以保持一致地更新。

### Fluent 文件映射模式

用于 Mozilla Fluent 语言环境文件的 `.ftl` 映射：

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

Hyperlocalise 支持 Fluent 消息、属性、多行值以及 select/plural 值作为完整的翻译单元。属性使用带点的键，例如 `brand.title`。不支持 Fluent 术语，并且会在解析期间失败。

### JS/TS 区域设置模块模式

当你的应用直接导入 locale 对象时，请使用 JavaScript 或 TypeScript 的 locale 模块映射：

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

受支持的模块必须导出一个静态对象，例如：

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

Hyperlocalise 会保留注释、导入、导出语法以及非消息模块文本。它会拒绝动态值、计算属性键、展开属性、多个导出的区域设置对象以及插值模板字面量。

### Apple 字符串目录映射模式

用于 Xcode 字符串目录的`.xcstrings`映射：

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

Hyperlocalise 将目标值写入 `localizations[targetLocale]` 并保留目录元数据。`status` 和 `check` 从目录中读取请求的目标区域设置。变体和替换源条目必须包含源语言本地化，这样 Hyperlocalise 才能安全地提取源形式。

### Android XML 字符串资源映射

Android XML 支持有意限定于位于 `strings.xml` 下、名为字符串资源文件的文件，并且这些文件位于 `res/values*` 目录中。请在目标路径中使用 Android 语言环境限定符名称：

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

支持的资源条目是 `<string name="...">` 和 `<plurals name="..."><item quantity="...">`。标记为 `translatable="false"` 的资源会被保留并跳过。诸如 `<string-array>` 之类不受支持的可翻译资源形状会默认失败关闭，因此不会被静默丢弃。

### Java 属性文件映射模式

将 `.properties` 映射用于 Java 资源包，每个区域设置一个文件：

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

支持的条目是具有字符串值的扁平 Java 属性键。Hyperlocalise 在写入时会保留注释、分隔符和键的顺序；翻译后的值会以转义的单行`.properties`值写入。

## 规则

`llm.rules` 按组选择配置文件。

* `priority`：更高者获胜
* `group`：组名

`llm.rules` 是可选的。当没有规则匹配某个组时，Hyperlocalise 会回退到 `llm.profiles.default`。

## 缓存

`cache` 配置远程缓存客户端。

* `enabled`（可选）：为`run`启用远程缓存。
* `endpoint`（除非 `enabled=true`，否则为可选）：远程缓存服务端点。
* `project_key_env`（可选，除非`enabled=true`）：包含项目缓存键的环境变量。
* `timeout_seconds`（可选）：远程缓存请求超时时间（秒）。
* 如果你省略`groups`，每个存储桶都会针对每个目标区域设置运行。

提示变量：

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

## 高级示例

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

* 将组目标保留在 `locales.targets` 中。
* 保持组桶与 `buckets` 键对齐。
* 在 `profiles` 和 `rules` 之间保持配置文件名称一致。

`llm.profiles.<name>` 字段：

## 生成一个入门模板

`groups` 对于初学者配置是可选的。当你想按语言环境或文件集拆分执行时，再添加它。

* 将`hyperlocalise`用于`sync push`和`sync pull`任务。
* 保留 `storage` 用于特定提供商的 TMS 适配器配置。
* `profile`：个人资料名称
* `prompt`（已弃用，可选）：作为系统回退使用的旧版提示模板

## 验证提示

```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
```

## LLM 配置文件

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

`groups.<name>` 定义了要一起处理的内容。

## 分组

* `user_prompt`（可选）：显式用户消息模板
* `system_prompt`（可选）：显式系统消息模板
* `model`：提供者模型 ID
* `provider`: `openai`、`azure_openai`、`anthropic`、`gemini`、`bedrock`、`lmstudio`、`groq`、`mistral`，或`ollama`
* `buckets`：存储桶名称列表
* `targets`：`locales.targets`的子集