Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_charset_module.xml @ 963:2116a99dc304
"Nginx HTTP Server - Second Edition" book added.
author | Valentin Bartenev <vbart@nginx.com> |
---|---|
date | Mon, 12 Aug 2013 13:20:13 +0400 |
parents | 417dc982362e |
children | 95c3c3bbf1ce |
line wrap: on
line source
<?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="2"> <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>&#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/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> <para> <note> Until version 1.5.4, “<literal>application/x-javascript</literal>” was used as the default MIME type instead of “<literal>application/javascript</literal>”. </note> </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>