Module ngx_http_charset_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_charset_module

Example Configuration
Directives
charset
charset_map
charset_types
override_charset
source_charset

The ngx_http_charset_module 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.

Example Configuration

include conf/koi-win;

charset windows-1251;
source_charset koi8-r;

Directives

Syntax:

charset charset | off;

Default:

charset off;

Context:

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 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:

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, or
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:

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,
fastcgi_ignore_headers,
uwsgi_ignore_headers,
scgi_ignore_headers,
and
grpc_ignore_headers
directives.

Syntax:

charset_map charset1 charset2 { ... }

Default:

—

Context:

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:

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:

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.

Syntax:

charset_types mime-type ...;

Default:

charset_types text/html text/xml text/plain text/vnd.wap.wml
application/javascript application/rss+xml;

Context:

http, server, location

This directive appeared in version 0.7.9.

Enables module processing in responses with the specified MIME types
in addition to “text/html”.
The special value “*” matches any MIME type (0.8.29).

Until version 1.5.4, “application/x-javascript” was used
as the default MIME type instead of “application/javascript”.

Syntax:

override_charset on | off;

Default:

override_charset off;

Context:

http, server, location, if in location

Determines whether a conversion should be performed for answers
received from a proxied or a FastCGI/uwsgi/SCGI/gRPC server
when the answers 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.

It should be noted that 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.

Syntax:

source_charset charset;

Default:

—

Context:

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 directive, a conversion is performed.