<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_http_charset_module"
        link="/ru/docs/http/ngx_http_charset_module.html"
        lang="ru"
        rev="5">

<section id="summary">

<para>
Модуль <literal>ngx_http_charset_module</literal> добавляет указанную
кодировку в поле <header>Content-Type</header> заголовка ответа.
Кроме того, модуль может перекодировать данные из одной кодировки в другую
с некоторыми ограничениями:
<list type="bullet">

<listitem>
перекодирование осуществляется только в одну сторону — от сервера к клиенту,
</listitem>

<listitem>
перекодироваться могут только однобайтные кодировки
</listitem>

<listitem>
или однобайтные кодировки в UTF-8 и обратно.
</listitem>

</list>
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
include        conf/koi-win;

charset        windows-1251;
source_charset koi8-r;
</example>
</para>

</section>


<section id="directives" name="Директивы">

<directive name="charset">
<syntax><value>кодировка</value> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if в location</context>

<para>
Добавляет указанную кодировку в поле <header>Content-Type</header>
заголовка ответа.
Если эта кодировка отличается от указанной в директиве
<link id="source_charset"/>, то выполняется перекодирование.
</para>

<para>
Параметр <literal>off</literal> отменяет добавление кодировки
в поле <header>Content-Type</header> заголовка ответа.
</para>

<para>
Кодировка может быть задана с помощью переменной:
<example>
charset $charset;
</example>
В этом случае необходимо, чтобы все возможные значения переменной
присутствовали хотя бы один раз в любом месте конфигурации в виде
директив <link id="charset_map"/>, <link id="charset"/> или
<link id="source_charset"/>.
Для кодировок <literal>utf-8</literal>, <literal>windows-1251</literal>
и <literal>koi8-r</literal> для этого достаточно включить в конфигурацию
файлы <path>conf/koi-win</path>, <path>conf/koi-utf</path> и
<path>conf/win-utf</path>.
Для других кодировок можно просто сделать фиктивную таблицу перекодировки,
например:
<example>
charset_map iso-8859-5 _ { }
</example>
</para>

<para>
Кроме того, кодировка может быть задана в поле <header>X-Accel-Charset</header>
заголовка ответа.
Эту возможность можно запретить с помощью директив
<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"/>
и
<link doc="ngx_http_grpc_module.xml" id="grpc_ignore_headers"/>.
</para>

</directive>


<directive name="charset_map">
<syntax block="yes"><value>кодировка1</value> <value>кодировка2</value></syntax>
<default/>
<context>http</context>

<para>
Описывает таблицу перекодирования из одной кодировки в другую.
Таблица для обратного перекодирования строится на основании тех же данных.
Коды символов задаются в шестнадцатеричном виде.
Неописанные символы в пределах 80-FF заменяются на “<literal>?</literal>”.
При перекодировании из UTF-8 символы, отсутствующие в однобайтной кодировке,
заменяются на “<literal>&amp;#XXXX;</literal>”.
</para>

<para>
Пример:
<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>
При описании таблицы перекодирования в UTF-8, коды кодировки UTF-8 должны
быть указаны во второй колонке, например:
<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>
Полные таблицы преобразования из <literal>koi8-r</literal> в
<literal>windows-1251</literal> и из <literal>koi8-r</literal> и
<literal>windows-1251</literal> в <literal>utf-8</literal>
входят в дистрибутив и находятся в файлах <path>conf/koi-win</path>,
<path>conf/koi-utf</path> и <path>conf/win-utf</path>.
</para>

</directive>


<directive name="charset_types">
<syntax><value>mime-тип</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>
Разрешает работу модуля в ответах с указанными MIME-типами
в дополнение к “<literal>text/html</literal>”.
Специальное значение “<literal>*</literal>” соответствует любому MIME-типу
(0.8.29).
</para>

<para>
<note>
До версии 1.5.4 по умолчанию вместо MIME-типа
“<literal>application/javascript</literal>” использовался
“<literal>application/x-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 в location</context>

<para>
Определяет, выполнять ли перекодирование для ответов,
полученных от проксированного сервера или от FastCGI/uwsgi/SCGI/gRPC-сервера,
если в ответах уже указана кодировка в поле <header>Content-Type</header>
заголовка ответа.
Если перекодирование разрешено, то в качестве исходной кодировки
используется кодировка, указанная в полученном ответе.
<note>
Необходимо отметить, что если ответ был получен в подзапросе,
то, независимо от значения директивы <literal>override_charset</literal>,
всегда выполняется перекодирование из кодировки ответа в кодировку
основного запроса.
</note>
</para>

</directive>


<directive name="source_charset">
<syntax><value>кодировка</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if в location</context>

<para>
Задаёт исходную кодировку ответа.
Если эта кодировка отличается от указанной в директиве
<link id="charset"/>, то выполняется перекодирование.
</para>

</directive>

</section>

</module>