# HG changeset patch
# User Ruslan Ermilov <ru@nginx.com>
# Date 1327400125 0
# Node ID 55c1c4a1748f02ce66c7d43e6ce67c6ca20c73cf
# Parent  302222923e344675fd55c9de5fbde8e1dd6a4974
English translation of ngx_http_charset_module.

diff -r 302222923e34 -r 55c1c4a1748f xml/en/GNUmakefile
--- a/xml/en/GNUmakefile	Tue Jan 24 10:13:26 2012 +0000
+++ b/xml/en/GNUmakefile	Tue Jan 24 10:15:25 2012 +0000
@@ -49,6 +49,7 @@
 		http/ngx_http_auth_basic_module				\
 		http/ngx_http_autoindex_module				\
 		http/ngx_http_browser_module				\
+		http/ngx_http_charset_module				\
 		http/ngx_http_empty_gif_module				\
 		http/ngx_http_fastcgi_module				\
 		http/ngx_http_flv_module				\
diff -r 302222923e34 -r 55c1c4a1748f xml/en/docs/http/ngx_http_charset_module.xml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/xml/en/docs/http/ngx_http_charset_module.xml	Tue Jan 24 10:15:25 2012 +0000
@@ -0,0 +1,208 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_http_charset_module"
+        link="/en/docs/http/ngx_http_charset_module.html"
+        lang="en">
+
+<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>
+
+</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>”.
+</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>
diff -r 302222923e34 -r 55c1c4a1748f xml/en/docs/index.xml
--- a/xml/en/docs/index.xml	Tue Jan 24 10:13:26 2012 +0000
+++ b/xml/en/docs/index.xml	Tue Jan 24 10:15:25 2012 +0000
@@ -95,6 +95,11 @@
 </item>
 
 <item>
+<a href="/en/docs/http/ngx_http_charset_module.xml">
+ngx_http_charset_module</a>
+</item>
+
+<item>
 <a href="/en/docs/http/ngx_http_empty_gif_module.xml">
 ngx_http_empty_gif_module</a>
 </item>