# gt: General Translation CLI tool: .resx
URL: https://generaltranslation.com/zh/docs/cli/reference/formats/resx-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 General Translation CLI 翻译 .NET 资源文件（.resx 和 .resw）。RESX 文件格式的 API 参考。

CLI 可翻译 .NET `.resx` 文件中的字符串资源，也支持采用相同 schema 的 `.resw` 文件。译文会保留资源名称、注释、.NET 占位符，以及所有不含文本的资源。此功能需要 `gt` 2.23.1 或更高版本。

## 概览 [#overview]

| 主题                      | 说明                        |
| ----------------------- | ------------------------- |
| [配置](#config)           | 按 .NET 的约定匹配源文件并为译文命名。    |
| [翻译行为](#behavior)       | 哪些资源会被翻译，哪些保持不变。          |
| [占位符](#placeholders)    | 完整保留 .NET 复合格式占位符和命名占位符。  |
| [不翻译的资源](#untranslated) | CLI 不做处理的资源。              |
| [编码](#encoding)         | 解码并还原带字节顺序标记 (BOM) 的文本编码。 |
| [验证](#validation)       | 跳过空文件，并拒绝无效的 XML 文档。      |

## 配置 [#config]

在 `files` 下添加一个 `resx` 条目。.NET 项目会将默认语言的资源保存在 `Properties/Resources.resx` 等文件中，而每种语言的翻译则保存在同级目录下、以区域性 (culture) 命名的文件中，例如 `Properties/Resources.es.resx`。由于源文件的文件名中不包含区域设置，因此需要将 `include` 指向该文件，并使用 `transform` 为翻译输出文件命名。同时，请结合 `[locales]` 占位符使用 `exclude`，以免同级的翻译文件被当作源文件读取：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "resx": {
      "include": ["Properties/*.resx"],
      "exclude": ["Properties/*.[locales].resx"],
      "transform": "*.[locale].resx"
    }
  }
}
```

使用此配置时，CLI 会读取 `Properties/Resources.resx`，并生成 `Properties/Resources.es.resx` 和 `Properties/Resources.fr.resx`。

UWP 和 WinUI 项目会按语言将 `.resw` 文件分别存放在各自的目录中，例如 `Strings/en-US/Resources.resw`。对于这种目录结构，请使用 `[locale]` 占位符，并移除 `transform`：

```json title="gt.config.json"
{
  "defaultLocale": "en-US",
  "locales": ["es-ES", "fr-FR"],
  "files": {
    "resx": {
      "include": ["Strings/[locale]/Resources.resw"]
    }
  }
}
```

RESX 仅支持 `RESX` 输出格式，无法通过 `transformationFormat` 转换为其他文件格式。有关通用的文件键，请参阅[配置参考](/docs/cli/reference/config#files)。

## 翻译行为 [#behavior]

CLI 会翻译每个包含字符串的 `<data>` 条目。翻译后的文件是源文件的副本，只替换了其中的字符串值，因此会保留：

* 资源名称和条目顺序
* `<resheader>` 条目和 schema 块
* 不含文本的资源，例如图像、图标和尺寸
* 注释和缩进

条目上的 `<comment>` 会作为上下文传递给翻译引擎，因此可以借助它来区分简短或含义多样的字符串。注释中的 Microsoft 本地化指令 (例如 `{Locked}` 和 `{Locked="Power Display"}`) 会作为需要遵循的指令一并传递。

包含 XML 的值 (例如注释或内联标签) 会按 XML 进行翻译，且必须保持格式良好。如果某个名称出现多次，CLI 只翻译第一个条目 (即 .NET 实际读取的条目) ，其余条目保持不变。

对于未更改的条目，其现有翻译可以复用，除非你选择强制重新翻译。

## 占位符 [#placeholders]

翻译会原样保留每个 .NET 占位符，包括其格式和对齐方式：

| 占位符   | 示例                       |
| ----- | ------------------------ |
| 复合格式  | `{0}`、`{0:N2}`、`{1,-10}` |
| 命名占位符 | `{count}`、`{Name:0.00}`  |
| 字面大括号 | `{{` 和 `}}`              |

占位符可以在句中调整位置，以适应目标语言的词序，但出现次数必须与源文本一致。如果某条翻译修改或遗漏了占位符，或者破坏了含 XML 的值中的 XML 结构，该翻译将不会写入翻译后的文件，.NET 会针对该条目回退到源语言。下次运行时会重新尝试翻译。

字母前的单个 `&` 用于标记键盘访问键，例如 `&File`。译文会在翻译后单词中的合适字母前保留一个 `&`。

## 不翻译的资源 [#untranslated]

CLI 会将以下资源原样保留在翻译后的文件中，不会将其发送去翻译：

* 带有 `mimetype` 的条目，这类条目存储的是图像等二进制数据
* `type` 不是 `System.String` 的条目，例如 `System.Drawing.Size`
* Windows Forms 设计器条目，其名称以 `>>` 开头
* 值为空的条目

## 编码 [#encoding]

对于不带字节顺序标记 (BOM) 的 `.resx` 文件，CLI 会按 UTF-8 读取。如果文件以字节顺序标记开头，CLI 支持 UTF-8、UTF-16 (小端序或大端序) 以及 UTF-32 (小端序或大端序) 。Visual Studio 默认将 `.resx` 文件保存为带字节顺序标记的 UTF-8 格式。下载的翻译文件会沿用源文件的编码和字节顺序标记。

不带字节顺序标记的 UTF-16 或 UTF-32 文件会被当作 UTF-8 处理。翻译前，请为文件添加相应的字节顺序标记，或将其另存为 UTF-8 格式。

## 验证 [#validation]

CLI 会跳过空的 `.resx` 文件，并在命令摘要中列出该文件。如果文件不是格式良好的 XML，或其顶层元素不是 `<root>`，API 将拒绝该文件。

## Sitemap

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