<!-- review: finished -->

<a id="http-charset"></a>

# Charset

The module adds the specified charset to the `Content-Type` response header field. In addition, the module can convert data from one charset to another, with some limitations:

* conversion is performed one way — from server to client,
* only single-byte charsets can be converted
* or single-byte charsets to/from UTF-8.

<a id="configuration-example-10"></a>

## Configuration Example

```nginx
include        conf/koi-win;

charset        windows-1251;
source_charset koi8-r;
```

<a id="directives-11"></a>

## Directives

<a id="index-0"></a>

<a id="id1"></a>

### charset

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `charset` charset | `off`;             |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `charset off;`                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

Adds the specified charset to the `Content-Type` response header field. If this charset is different from the charset specified in the [source_charset](#source-charset) directive, a conversion is performed.

The parameter `off` cancels the addition of charset to the `Content-Type` response header field.

A charset can be defined with a variable:

```nginx
charset $charset;
```

In such a case, all possible values of a variable need to be present in the
configuration at least once in the form of the [charset_map](#charset-map),
[charset](#id1), or [source_charset](#source-charset) directives. For `utf-8`,
`windows-1251`, and `koi8-r` charsets, it is sufficient to include
the files `conf/koi-win`, `conf/koi-utf`, and `conf/win-utf`
into configuration. For other charsets, simply making a fictitious conversion
table works, for example:

```nginx
charset_map iso-8859-5 _ { }
```

In addition, a charset can be set in the `X-Accel-Charset` response header field. This capability can be disabled using the [proxy_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-headers), [fastcgi_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-ignore-headers), [uwsgi_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-ignore-headers), [scgi_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-ignore-headers), and [grpc_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ignore-headers) directives.

<a id="index-1"></a>

<a id="charset-map"></a>

### charset_map

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `charset_map` charset1 charset2  { ... }   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                       |

Describes the conversion table from one charset to another. A reverse conversion table is built using the same data. Character codes are given in hexadecimal. Missing characters in the range 80-FF are replaced with "?". When converting from UTF-8, characters missing in a one-byte charset are replaced with "&#XXXX;".

Example:

```nginx
charset_map koi8-r windows-1251 {
    C0 FE ; # small yu
    C1 E0 ; # small a
    C2 E1 ; # small b
    C3 F6 ; # small ts
}
```

When describing a conversion table to UTF-8, codes for the UTF-8 charset should be given in the second column, for example:

```nginx
charset_map koi8-r utf-8 {
    C0 D18E ; # small yu
    C1 D0B0 ; # small a
    C2 D0B1 ; # small b
    C3 D186 ; # small ts
}
```

Full conversion tables from `koi8-r` to `windows-1251`, and from
`koi8-r` and `windows-1251` to `utf-8` are provided in the
distribution files `conf/koi-win`, `conf/koi-utf`, and
`conf/win-utf`.

<a id="index-2"></a>

<a id="charset-types"></a>

### charset_types

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `charset_types` mime-type ...;                                                                             |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `charset_types text/html text/xml text/plain text/vnd.wap.wml application/javascript application/rss+xml;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                     |

Enables module processing in responses with the specified MIME types in addition to `text/html`. The special value `*` matches any MIME type.

<a id="index-3"></a>

<a id="override-charset"></a>

### override_charset

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `override_charset` `on` | `off`;       |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `override_charset off;`                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

Determines whether a conversion should be performed for responses received from a proxied or a FastCGI/uwsgi/SCGI/gRPC server when the responses already carry a charset in the `Content-Type` response header field. If conversion is enabled, a charset specified in the received response is used as a source charset.

#### NOTE
If a response is received in a subrequest then the conversion from the response charset to the main request charset is always performed, regardless of the override_charset directive setting.

<a id="index-4"></a>

<a id="source-charset"></a>

### source_charset

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `source_charset` charset;              |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

Defines the source charset of a response. If this charset is different from the charset specified in the [charset](#id1) directive, a conversion is performed.