<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.search.lucene.charset">
    <title>Conjunto de Caracteres</title>

    <sect2 id="zend.search.lucene.charset.description">
        <title>Suporte aos conjuntos de caracteres UTF-8 e single-byte</title>

        <para>
            <classname>Zend_Search_Lucene</classname> trabalha internamente com o conjunto de
            caracteres UTF-8. Arquivos de índice armazenam dados unicode no formato de codificação
            "UTF-8 modificado" usado pelo Java. O núcleo do
            <classname>Zend_Search_Lucene</classname> suporta esta codificação plenamente, com uma
            exceção.

            <footnote>
               <para>
                   <classname>Zend_Search_Lucene</classname> suporta somente os caracteres do Plano
                   Multilingual Básico (BMP) (de 0x0000 a 0xFFFF), não suportando os caracteres
                   suplementares (caracteres acima de 0xFFFF)
               </para>

               <para>
                   O Java 2 representa estes caracteres como um par de valores do tipo char
                   (16 bits), o primeiro vem da faixa superior (0xD800-0xDBFF), o segundo, da faixa
                   inferior (0xDC00-0xDFFF). Logo eles são codificados como caracteres usuais UTF-8
                   em seis bytes. A representação padrão UTF-8 utiliza quatro bytes para caracteres
                   suplementares.
               </para>
            </footnote>
        </para>

        <para>
            A codificação dos dados de entrada pode ser especificada através da
            <acronym>API</acronym> de <classname>Zend_Search_Lucene</classname>. Os dados serão
            convertidos automaticamente na codificação UTF-8.
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.charset.default_analyzer">
        <title>Analisador de texto padrão</title>

        <para>
            De qualquer modo, o analisador de texto padrão (que também é usado no analisador de
            consultas) utiliza ctype_alpha() para a separação de texto e consultas em tokens.
        </para>

        <para>
            ctype_alpha() não é compatível com UTF-8, por isso o analisador converte o texto para a
            codificação 'ASCII//TRANSLIT' antes da indexação. O mesmo processo é realizado
            transparentemente durante a análise da consulta.

            <footnote>
               <para>
                   A conversão para 'ASCII//TRANSLIT' depende da localidade atual e do SO.
               </para>
            </footnote>
        </para>

        <note>
            <title/>
            <para>
                O analisador padrão não trata os números como parte de termos. Utilize o analisador
                'Num' correspondente se você não quer que palavras sejam quebradas por números.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.search.lucene.charset.utf_analyzer">
        <title>Analisadores de texto compatíveis com UTF-8</title>

        <para>
            <classname>Zend_Search_Lucene</classname> também contém um conjunto de analisadores
            compatíveis com UTF-8:
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Utf8</classname>,
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Utf8Num</classname>,
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Utf8_CaseInsensitive</classname>,
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Utf8Num_CaseInsensitive</classname>.
        </para>

        <para>
            Qualquer um desses analisadores pode ser ativado como o código a seguir:
        </para>

        <programlisting language="php"><![CDATA[
Zend_Search_Lucene_Analysis_Analyzer::setDefault(
    new Zend_Search_Lucene_Analysis_Analyzer_Common_Utf8());
]]></programlisting>

        <warning>
            <title/>
            <para>
                Os analisadores compatíveis com UTF-8 foram melhorados no Zend Framework 1.5. As
                primeiras versões dos analisadores assumiam como sendo letras todos os caracteres
                que não fossem ASCII. A implementação dos novos analisadores possui um comportamento
                mais correto.
            </para>

            <para>
                Isso pode exigir que você reconstrua o índice para ter os dados e as consultas de
                pesquisas separados em tokens do mesmo formato, caso contrário o motor de busca pode
                retornar conjuntos de resultados errados.
            </para>
        </warning>

        <para>
            Todos estes analisadores necessitam da biblioteca PCRE (Perl-compatible regular
            expressions) compilada com suporte à UTF-8 ativado. O suporte à UTF-8 do PCRE está
            ativado nas fontes da biblioteca PCRE fornecidas com o código fonte do
            <acronym>PHP</acronym>, mas se uma biblioteca compartilhada é usada em vez do pacote com
            as fontes do <acronym>PHP</acronym>, então o estado do suporte à UTF-8 vai depender de
            seu sistema operacional.
        </para>

        <para>
            Use o seguinte código para verificar, se o PCRE com suporte à UTF-8 está habilitado:
        </para>

        <programlisting language="php"><![CDATA[
if (@preg_match('/\pL/u', 'a') == 1) {
    echo "PCRE com suporte a Unicode está ativado.\n";
} else {
    echo "PCRE com suporte a Unicode está desativado.\n";
}
]]></programlisting>

        <para>
            Versões dos analisadores compatíveis com UTF-8 insensíveis a maiúsculas e minúsculas
            precisam também da extensão <ulink
                url="http://www.php.net/manual/en/ref.mbstring.php">mbstring</ulink> habilitada.
        </para>

        <para>
            Se você não quer ativar a extensão mbstring, mas precisa de buscas sem diferenciação de
            maiúsculas e minúsculas, pode-se usar a seguinte abordagem: normalizar os dados antes da
            indexação e a string de consulta antes de pesquisar, convertendo-os em minúsculas:
        </para>

        <programlisting language="php"><![CDATA[
// Indexando
setlocale(LC_CTYPE, 'de_DE.iso-8859-1');

...

Zend_Search_Lucene_Analysis_Analyzer::setDefault(
    new Zend_Search_Lucene_Analysis_Analyzer_Common_Utf8());

...

$doc = new Zend_Search_Lucene_Document();

$doc->addField(Zend_Search_Lucene_Field::UnStored('contents',
                                                  strtolower($contents)));

// Título de campo para pesquisa direta (indexado, não armazenado)
$doc->addField(Zend_Search_Lucene_Field::UnStored('title',
                                                  strtolower($title)));

// Título de campo para recuperação (não indexado, armazenado)
$doc->addField(Zend_Search_Lucene_Field::UnIndexed('_title', $title));
]]></programlisting>

        <programlisting language="php"><![CDATA[
// Buscando
setlocale(LC_CTYPE, 'de_DE.iso-8859-1');

...

Zend_Search_Lucene_Analysis_Analyzer::setDefault(
    new Zend_Search_Lucene_Analysis_Analyzer_Common_Utf8());

...

$hits = $index->find(strtolower($query));
]]></programlisting>
    </sect2>
</sect1>
