Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_charset_module.xml @ 2846:fdf1464e1977
Moved banner to the external file to make partial rollout possible.
An idea is to have several banners and show them with different probability
specified by split directive in the nginx.conf
author | Sergey Budnevitch <sb@waeme.net> |
---|---|
date | Tue, 10 May 2022 18:07:27 +0400 |
parents | 4cafd82e5007 |
children | ddf686b02ceb |
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="5"> <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, a charset can be set in the <header>X-Accel-Charset</header> response header field. This capability can be disabled using the <link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/>, <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_ignore_headers"/>, <link doc="ngx_http_uwsgi_module.xml" id="uwsgi_ignore_headers"/>, <link doc="ngx_http_scgi_module.xml" id="scgi_ignore_headers"/>, and <link doc="ngx_http_grpc_module.xml" id="grpc_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 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 <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 is received in a subrequest then the 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>