# General Translation Platform: CustomMapping
URL: https://generaltranslation.com/zh/docs/platform/core/reference/types/custom-mapping.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 自定义区域设置映射及区域设置属性覆盖。CustomMapping 类型的 API 参考。

`CustomMapping` 定义了自定义区域设置代码映射和元数据，可用于扩展或覆盖标准 BCP-47 区域设置信息。你可以将其作为 `customMapping` 选项传递给 General Translation 的 [Constructor](/docs/platform/core/reference/gt-class/constructor)，也可以在 [`GTConstructorParams`](/docs/platform/core/reference/types/gt-constructor-params) 中使用。

## 概览 [#overview]

`CustomMapping` 是一种记录类型，以自定义区域设置代码或别名为键。每个值可以是显示名称字符串，也可以是部分 [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties) 对象，用于覆盖特定的区域设置元数据。

```typescript
type CustomMapping = Record<string, string | Partial<LocaleProperties>>;
```

自定义映射会在 GT 实例初始化时解析，且其优先级高于标准的 BCP-47 区域设置解析。

## 结构 [#structure]

* **键** — 自定义区域设置代码或别名，例如 `'simplified-chinese'` 或 `'company-english'`。
* **值** — 可以是简单的显示名称 `string`，也可以是一个 `Partial<LocaleProperties>` 对象。

| 值类型                         | 描述           | 示例                                                  |
| --------------------------- | ------------ | --------------------------------------------------- |
| `string`                    | 简单的显示名称。     | `'Simplified Chinese'`                              |
| `Partial<LocaleProperties>` | 对区域设置元数据的覆盖。 | `{ code: 'zh-CN', name: 'Chinese', emoji: '🇨🇳' }` |

## 示例 [#example]

```typescript
// 简单字符串映射：alias -> display name
const simpleMapping: CustomMapping = {
  'english': 'English',
  'spanish': 'Spanish',
  'mexican-spanish': 'Mexican Spanish'
};

const gt = new GT({
  sourceLocale: 'english',
  targetLocale: 'spanish',
  customMapping: simpleMapping
});
```

```typescript
// 增强的区域设置元数据覆盖
const enhancedMapping: CustomMapping = {
  'simplified-chinese': {
    code: 'zh-CN',
    name: 'Simplified Chinese',
    nativeName: '简体中文',
    regionName: 'China',
    emoji: '🇨🇳'
  }
};
```

## 备注 [#notes]

* 自定义映射会覆盖标准的 BCP-47 区域设置解析，因此别名可以绕过标准的区域设置校验 (例如，将 `cn` 用作 `zh` 的别名) 。
* 字符串值可提供简单的显示名称；`Partial<LocaleProperties>` 值则支持更细致的区域设置自定义，例如自定义名称和 emoji。
* 自定义映射会在 GT 实例初始化时解析。
* 对于区域级覆盖，[`getRegionProperties`](/docs/platform/core/reference/gt-class-methods/locales/get-region-properties) 接受单独的 `CustomRegionMapping` 类型。

## Sitemap

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