Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_charset_module.xml @ 350:55c1c4a1748f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
English translation of ngx_http_charset_module.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 24 Jan 2012 10:15:25 +0000
parents
children a4fa80755eab
comparison
equal deleted inserted replaced
349:302222923e34 350:55c1c4a1748f
1 <?xml version="1.0"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Module ngx_http_charset_module"
6 link="/en/docs/http/ngx_http_charset_module.html"
7 lang="en">
8
9 <section id="summary">
10
11 <para>
12 The <literal>ngx_http_charset_module</literal> module adds the specified
13 charset to the <header>Content-Type</header> response header field.
14 In addition, the module can convert data from one charset to another,
15 with some limitations:
16 <list type="bullet">
17
18 <listitem>
19 conversion is performed one way — from server to client,
20 </listitem>
21
22 <listitem>
23 only single-byte charsets can be converted
24 </listitem>
25
26 <listitem>
27 or single-byte charsets to/from UTF-8.
28 </listitem>
29
30 </list>
31 </para>
32
33 </section>
34
35
36 <section id="example" name="Example Configuration">
37
38 <para>
39 <example>
40 include conf/koi-win;
41
42 charset windows-1251;
43 source_charset koi8-r;
44 </example>
45 </para>
46
47 </section>
48
49
50 <section id="directives" name="Directives">
51
52 <directive name="charset">
53 <syntax><value>charset</value> | <literal>off</literal></syntax>
54 <default>off</default>
55 <context>http</context>
56 <context>server</context>
57 <context>location</context>
58 <context>if in location</context>
59
60 <para>
61 Adds the specified charset to the <header>Content-Type</header>
62 response header field.
63 If this charset is different from the charset specified
64 in the <link id="source_charset"/> directive, a conversion is performed.
65 </para>
66
67 <para>
68 The parameter <literal>off</literal> cancels the addition of charset
69 to the <header>Content-Type</header> response header field.
70 </para>
71
72 <para>
73 A charset can be defined with a variable:
74 <example>
75 charset $charset;
76 </example>
77 In such a case, all possible values of a variable need to be present
78 in the configuration at least once in the form of the
79 <link id="charset_map"/>, <link id="charset"/>, or
80 <link id="source_charset"/> directives.
81 For <literal>utf-8</literal>, <literal>windows-1251</literal>, and
82 <literal>koi8-r</literal> charsets it is sufficient to include the files
83 <path>conf/koi-win</path>, <path>conf/koi-utf</path>, and
84 <path>conf/win-utf</path> into configuration.
85 For other charsets, simply making a fictitious conversion table works,
86 for example:
87 <example>
88 charset_map iso-8859-5 _ { }
89 </example>
90 </para>
91
92 </directive>
93
94
95 <directive name="charset_map">
96 <syntax block="yes"><value>charset1</value> <value>charset2</value></syntax>
97 <default/>
98 <context>http</context>
99
100 <para>
101 Describes the conversion table from one charset to another.
102 A reverse conversion table is built using the same data.
103 Character codes are given in hexadecimal.
104 Missing characters in the range 80-FF are replaced with “<literal>?</literal>”.
105 When converting from UTF-8, characters missing in a one-byte charset
106 are replaced with “<literal>&amp;#XXXX;</literal>”.
107 </para>
108
109 <para>
110 Example:
111 <example>
112 charset_map koi8-r windows-1251 {
113 C0 FE ; # small yu
114 C1 E0 ; # small a
115 C2 E1 ; # small b
116 C3 F6 ; # small ts
117 ...
118 }
119 </example>
120 </para>
121
122 <para>
123 When describing a conversion table to UTF-8, codes for the UTF-8 charset should
124 be given in the second column, for example:
125 <example>
126 charset_map koi8-r utf-8 {
127 C0 D18E ; # small yu
128 C1 D0B0 ; # small a
129 C2 D0B1 ; # small b
130 C3 D186 ; # small ts
131 ...
132 }
133 </example>
134 </para>
135
136 <para>
137 Full conversion tables from <literal>koi8-r</literal> to
138 <literal>windows-1251</literal>, and from <literal>koi8-r</literal> and
139 <literal>windows-1251</literal> to <literal>utf-8</literal>
140 are provided in the distribution files <path>conf/koi-win</path>,
141 <path>conf/koi-utf</path>, and <path>conf/win-utf</path>.
142 </para>
143
144 </directive>
145
146
147 <directive name="charset_types">
148 <syntax><value>mime-type</value> ...</syntax>
149 <default>text/html text/xml text/plain text/vnd.wap.wml
150 application/x-javascript application/rss+xml</default>
151 <context>http</context>
152 <context>server</context>
153 <context>location</context>
154 <appeared-in>0.7.9</appeared-in>
155
156 <para>
157 Enables module processing in responses with the specified MIME types
158 in addition to “<literal>text/html</literal>”.
159 </para>
160
161 </directive>
162
163
164 <directive name="override_charset">
165 <syntax><literal>on</literal> | <literal>off</literal></syntax>
166 <default>off</default>
167 <context>http</context>
168 <context>server</context>
169 <context>location</context>
170 <context>if in location</context>
171
172 <para>
173 Determines if a conversion should be performed for answers
174 received from a proxied or FastCGI server,
175 if the answers already carry a charset in the <header>Content-Type</header>
176 response header field.
177 If conversion is enabled, a charset specified in the received
178 response is used as a source charset.
179 <note>
180 It should be noted that if a response was received in a subrequest
181 then conversion from the response charset to the main request charset
182 is always performed regardless of the <literal>override_charset</literal>
183 directive setting.
184 </note>
185 </para>
186
187 </directive>
188
189
190 <directive name="source_charset">
191 <syntax><value>charset</value></syntax>
192 <default/>
193 <context>http</context>
194 <context>server</context>
195 <context>location</context>
196 <context>if in location</context>
197
198 <para>
199 Defines the source charset of a response.
200 If this charset is different from the charset specified
201 in the <link id="charset"/> directive, a conversion is performed.
202 </para>
203
204 </directive>
205
206 </section>
207
208 </module>