<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_charset_module"
        link="/en/docs/http/ngx_http_charset_module.html"
        lang="en"
        rev="1">

<section id="summary">

<para>
The <literal>ngx_http_charset_module</literal> module adds the specified
charset to the <header>Content-Type</header> response header field.
In addition, the module can convert data from one charset to another,
with some limitations:
<list type="bullet">

<listitem>
conversion is performed one way — from server to client,
</listitem>

<listitem>
only single-byte charsets can be converted
</listitem>

<listitem>
or single-byte charsets to/from UTF-8.
</listitem>

</list>
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
include        conf/koi-win;

charset        windows-1251;
source_charset koi8-r;
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="charset">
<syntax><value>charset</value> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if in location</context>

<para>
Adds the specified charset to the <header>Content-Type</header>
response header field.
If this charset is different from the charset specified
in the <link id="source_charset"/> directive, a conversion is performed.
</para>

<para>
The parameter <literal>off</literal> cancels the addition of charset
to the <header>Content-Type</header> response header field.
</para>

<para>
A charset can be defined with a variable:
<example>
charset $charset;
</example>
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
<link id="charset_map"/>, <link id="charset"/>, or
<link id="source_charset"/> directives.
For <literal>utf-8</literal>, <literal>windows-1251</literal>, and
<literal>koi8-r</literal> charsets it is sufficient to include the files
<path>conf/koi-win</path>, <path>conf/koi-utf</path>, and
<path>conf/win-utf</path> into configuration.
For other charsets, simply making a fictitious conversion table works,
for example:
<example>
charset_map iso-8859-5 _ { }
</example>
</para>

<para>
In addition, charset can also be set in the
<header>X-Accel-Charset</header> response header field.
This ability can be disabled using the
<link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/>
and
<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_ignore_headers"/>
directives.
</para>

</directive>


<directive name="charset_map">
<syntax block="yes"><value>charset1</value> <value>charset2</value></syntax>
<default/>
<context>http</context>

<para>
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 “<literal>?</literal>”.
When converting from UTF-8, characters missing in a one-byte charset
are replaced with “<literal>&amp;#XXXX;</literal>”.
</para>

<para>
Example:
<example>
charset_map koi8-r windows-1251 {
    C0 FE ; # small yu
    C1 E0 ; # small a
    C2 E1 ; # small b
    C3 F6 ; # small ts
    ...
}
</example>
</para>

<para>
When describing a conversion table to UTF-8, codes for the UTF-8 charset should
be given in the second column, for example:
<example>
charset_map koi8-r utf-8 {
    C0 D18E ; # small yu
    C1 D0B0 ; # small a
    C2 D0B1 ; # small b
    C3 D186 ; # small ts
    ...
}
</example>
</para>

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

</directive>


<directive name="charset_types">
<syntax><value>mime-type</value> ...</syntax>
<default>text/html text/xml text/plain text/vnd.wap.wml
application/x-javascript application/rss+xml</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.7.9</appeared-in>

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

</directive>


<directive name="override_charset">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if in location</context>

<para>
Determines if a conversion should be performed for answers
received from a proxied or FastCGI server,
if the answers already carry a charset in the <header>Content-Type</header>
response header field.
If conversion is enabled, a charset specified in the received
response is used as a source charset.
<note>
It should be noted that if a response was received in a subrequest
then conversion from the response charset to the main request charset
is always performed regardless of the <literal>override_charset</literal>
directive setting.
</note>
</para>

</directive>


<directive name="source_charset">
<syntax><value>charset</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if in location</context>

<para>
Defines the source charset of a response.
If this charset is different from the charset specified
in the <link id="charset"/> directive, a conversion is performed.
</para>

</directive>

</section>

</module>