# gt: General Translation CLI tool: Android strings.xml
URL: https://generaltranslation.com/zh/docs/cli/reference/formats/android-strings-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 CLI 翻译 Android strings.xml 资源文件。Android strings.xml 文件格式的 API 参考。

CLI 可翻译 Android 字符串资源。Android 项目将默认语言的字符串保存在 `res/values/strings.xml` 中，并将每种翻译放在带区域设置限定符的同级目录下，例如 `res/values-es/strings.xml`。翻译会保留资源名称、`<xliff:g>` 占位符，以及应用所渲染的内联标记。

## 概览 [#overview]

| 主题                      | 说明                               |
| ----------------------- | -------------------------------- |
| [配置](#config)           | 将基础资源文件分发到带区域设置限定符的目录中。          |
| [资源目录限定符](#qualifiers)  | 区域设置代码在 `values-*` 目录名中的书写方式。    |
| [复数](#plurals)          | 按各目标语言的 CLDR 类别重新生成 `<plurals>`。 |
| [未翻译的资源](#untranslated) | CLI 不作处理的资源。                     |

## 配置 [#config]

在 `files` 下添加一个 `androidStrings` 条目。Android 的基础资源文件是 `res/values/strings.xml`，其路径中不含区域设置限定符，因此无处放置 `[locale]` 占位符。请将 `include` 指向该基础文件，并使用 `transform` 将翻译输出导向带区域设置限定符的目录：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "pl"],
  "files": {
    "androidStrings": {
      "include": ["res/values/strings.xml"],
      "transform": {
        "match": "res/values/(.*)",
        "replace": "res/values-{locale}/$1"
      }
    }
  }
}
```

使用此配置时，CLI 会读取 `res/values/strings.xml`，并写入 `res/values-es/strings.xml`、`res/values-fr/strings.xml` 和 `res/values-pl/strings.xml`。完整的文件键列表请参见[配置参考](/docs/cli/reference/config#files)。

标准 Android 项目应采用这种结构，它与其他文件格式不同：像 `res/values-[locale]/strings.xml` 这样的模式会把占位符解析为你的 `defaultLocale`，进而去查找 `res/values-en/strings.xml`，而标准项目中并没有这个文件。结果是匹配不到任何文件，本次运行不会翻译任何内容便告结束。

如果你的项目确实把源字符串放在 `res/values-en/` 这类带限定符的目录中，则改用占位符形式，并去掉 `transform`：

```json title="gt.config.json"
{
  "files": {
    "androidStrings": {
      "include": ["res/values-[locale]/strings.xml"]
    }
  }
}
```

`androidStrings` 键需要 `gt` 2.19.0 或更高版本。

## 资源目录限定符 [#qualifiers]

Android 会从 `values-*` 目录名中解析区域设置，若遇到无法解析的名称则会导致 build 失败，因此路径中的区域设置未必与你在 [`locales`](/docs/cli/reference/config#locales) 中所写的拼写一致。对于 `androidStrings`，CLI 会在 `[locale]` 占位符和 `{locale}` 转换占位符中，将区域设置转换为 Android 资源限定符：

| 配置的区域设置   | 资源目录                   |
| --------- | ---------------------- |
| `es`      | `res/values-es`        |
| `fr-CA`   | `res/values-fr-rCA`    |
| `zh-Hans` | `res/values-b+zh+Hans` |
| `es-419`  | `res/values-b+es+419`  |

region subtag 采用 legacy 的 `-r` 形式，而 script subtag 或数字形式的 region 则使用 BCP 47 的 `b+` 形式。该转换仅适用于 `androidStrings`；其他所有文件格式均按配置原样使用区域设置。

## 复数 [#plurals]

Android 的数量字符串是 `<plurals>` 元素，其中每个 CLDR 类别对应一个 `<item quantity="...">`。翻译后的文件只包含目标语言实际使用的类别，这些类别与源语言的往往并不相同。英语只在 `one` 和 `other` 之间选择，而波兰语对整数计数有三种形式，阿拉伯语有六种，中文只有一种。

```xml title="res/values/strings.xml"
<plurals name="photo_count">
  <item quantity="one">%d photo</item>
  <item quantity="other">%d photos</item>
</plurals>
```

CLI 会按照目标语言的 CLDR 规则重建每个 `<plurals>`，补上该语言需要的类别，并删除它永远不会选用的类别。Android 完全依赖 CLDR 来解析数量，因此目标语言不使用的类别无法被触达，会被移除，包括源文件中已有的 `zero`。不要期望翻译后的 element 与 source 拥有相同的 `quantity` 值；应改为在有代表性的 count 下比较渲染输出。

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

当资源包含可翻译文本时，CLI 会翻译 `<string>` 的值以及 `<string-array>` 中的每一项。

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

* 标记为 `translatable="false"` 的资源，这是排除 API 密钥、品牌名称和调试值的标准做法。该属性的匹配方式与 AAPT 的读取方式一致，因此 `False` 和 `FALSE` 同样有效。
* 未加引号、且去除首尾空白后以 `@` 或 `?` 开头的值，这类值引用的是其他资源，而非包含文本。加引号的值以及转义的 `\@` 值仍可翻译。
* 只要 `<plurals>` 或 `<string-array>` 中有任意一项是资源引用，整个资源都会被跳过。CLI 会保持整个资源不变，以免产生无效的引用。
* 不含面向用户文本的资源类型，例如 `<bool>`、`<integer>` 和 `<color>`。

资源上方的注释会作为上下文传递给翻译引擎，因此可以用注释来消除简短或含义多重的字符串的歧义。

## Sitemap

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