Module ngx_http_charset_module
Join us for the first quarterly
NGINX Community Call
on July 22nd to connect and discuss NGINX development.
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_moduleExample 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.