# General Translation Integrations: 元数据文件
URL: https://generaltranslation.com/zh/docs/integrations/paraglide/reference/metadata-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 存放 Paraglide JS 消息源代码上下文的文件。元数据文件参考。

元数据文件与基础区域设置的消息文件放在同一目录下，结构与之一一对应：`messages/en.json` 对应 `messages/en.metadata.json`。它采用[键级元数据](/docs/cli/reference/keyed-metadata)格式，因此 CLI 会将其与消息一并上传。

## 格式 [#format]

每条被使用的消息都有一个 [`sourceCode`](/docs/cli/reference/keyed-metadata#source-code) 字段，按源文件列出该消息各处使用位置附近的代码。路径均相对于项目根目录。

```json title="messages/en.json"
{
  "greeting": "Hello, {username}!",
  "legacy_banner": "Welcome back"
}
```

```json title="messages/en.metadata.json"
{
  "greeting": {
    "sourceCode": {
      "src/Header.tsx": [
        {
          "before": "import { m } from './paraglide/messages.js';\n…",
          "target": "  return <h1>{m.greeting({ username })}</h1>;",
          "after": "}\n…"
        }
      ]
    }
  }
}
```

`legacy_banner` 未在应用中使用，因此没有对应的条目。

| 字段       | 描述                                                                                                   | 类型       |
| -------- | ---------------------------------------------------------------------------------------------------- | -------- |
| `before` | 调用位置上方的代码行：默认 10 行，可通过 [`radius`](/docs/integrations/paraglide/reference/collect-context#radius) 设置。 | `string` |
| `target` | 调用位置本身所在的代码行。                                                                                        | `string` |
| `after`  | 调用位置下方的代码行。                                                                                          | `string` |

## 会写入哪些文件和键 [#written]

* **仅限基础区域设置。** 其他区域设置的文件 (例如 `messages/fr.json`) 不会生成元数据文件，因为上下文对每种目标语言都相同。
* **仅限消息文件中的键。** 只写入消息文件中存在的键，因为 CLI 会拒绝源文件中不存在的元数据键。嵌套的键会保留嵌套结构。
* **仅限已使用的消息。** 未使用的消息不会有对应条目。
* **动态名称。** 像 ``m[`error_${code}`]`` 这样的计算名称会写入所有匹配 `error_*` 的消息。单独的 `m[key]` 则不会写入任何消息。
* **多个 inlang 项目。** 每处用法会归入编译出其 Paraglide JS 输出目录的那个项目。

消息文件依据每个 inlang 项目的 `settings.json` 读取，即其中的 `baseLocale` 以及 `plugin.inlang.messageFormat` 的 `pathPattern`。

## 文件如何更新 [#updates]

* 每次运行都会替换 `sourceCode`。你手动填写的字段 ([`context`](/docs/cli/reference/keyed-metadata#context) 和 [`maxChars`](/docs/cli/reference/keyed-metadata#max-chars)) 会被保留。
* 文件以原子方式写入，且仅在内容发生变化时才会写入。
* 如果元数据文件无法读取或不是 JSON 对象，则保持原样，并给出警告。
* 如果项目不再导入 Paraglide JS，其元数据文件将保持原样：因为找不到其输出目录，也就找不到对应的 inlang 项目。

## 限制 [#limits]

* 多个应用共享同一个 inlang 项目时，会相互覆盖彼此的 `sourceCode`，以最后分析的应用为准。
* 由其他 inlang 格式插件 (例如 i18next) 存储的消息不会生成元数据文件。
* 翻译服务对每个文件只读取有限数量的条目，并会截断过长的条目。 (参见 [`sourceCode`](/docs/cli/reference/keyed-metadata#source-code)。)

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.