Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_charset_module.xml @ 350:55c1c4a1748f
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>&#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> |