# General Translation Platform: CustomMapping
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/types/custom-mapping.mdx
---

title: CustomMapping
description: Custom locale mappings and locale property overrides. API reference for CustomMapping type.

---

`CustomMapping` defines custom locale code mappings and metadata that extend or override standard BCP-47 locale information. Pass it as the `customMapping` option to the General Translation [Constructor](/docs/platform/core/reference/gt-class/constructor) or in [`GTConstructorParams`](/docs/platform/core/reference/types/gt-constructor-params).

## Overview [#overview]

`CustomMapping` is a record keyed by a custom locale code or alias. Each value is either a display-name string or a partial [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties) object that overrides specific locale metadata.

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

Custom mappings are resolved when the GT instance is initialized, and they take precedence over standard BCP-47 locale resolution.

## Structure [#structure]

- **Keys** — custom locale codes or aliases, such as `'simplified-chinese'` or `'company-english'`.
- **Values** — either a simple display-name `string` or a `Partial<LocaleProperties>` object.

| Value type | Description | Example |
| --- | --- | --- |
| `string` | Simple display name. | `'Simplified Chinese'` |
| `Partial<LocaleProperties>` | Locale metadata overrides. | `{ code: 'zh-CN', name: 'Chinese', emoji: '🇨🇳' }` |

## Example [#example]

```typescript
// Simple string mappings: 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
// Enhanced locale metadata overrides
const enhancedMapping: CustomMapping = {
  'simplified-chinese': {
    code: 'zh-CN',
    name: 'Simplified Chinese',
    nativeName: '简体中文',
    regionName: 'China',
    emoji: '🇨🇳'
  }
};
```

## Notes [#notes]

- Custom mappings override standard BCP-47 locale resolution, so an alias can bypass the standard locale validation (for example, using `cn` as an alias for `zh`).
- String values provide simple display names; `Partial<LocaleProperties>` values allow detailed locale customization such as custom names and emojis.
- Custom mappings are resolved during GT instance initialization.
- For region-level overrides, [`getRegionProperties`](/docs/platform/core/reference/gt-class-methods/locales/get-region-properties) accepts a separate `CustomRegionMapping` type.