repo_zf1Php7/documentation/manual/en/module_specs/Zend_Translate-Migration.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.translate.migration">

    <title>Migrating from previous versions</title>

    <para>
        The API of <classname>Zend_Translate</classname> has changed from time to time.
        If you started to use <classname>Zend_Translate</classname> and its subcomponents
        in earlier versions follow the guidelines below to migrate your scripts to
        use the new API.
    </para>

    <sect2 id="zend.translate.migration.fromonesixtooneseven">
        <title>Migrating from 1.6 to 1.7 or newer</title>
        <sect3 id="zend.translate.migration.fromonesixtooneseven.languages">
            <title>Setting languages</title>

            <para>
                When using automatic detection of languages, or setting languages manually
                to <classname>Zend_Translate</classname> you may have mentioned that from time to time a
                notice is thrown about not added or empty translations. In some previous
                release also an exception was raised in some cases.
            </para>

            <para>
                The reason is, that when a user requests a non existing language, you
                have no simple way to detect what's going wrong. So we added those
                notices which show up in your log and tell you that the user requested
                a language which you do not support. Note that the code, even when
                we trigger such an notice, keeps working without problems.
            </para>

            <para>
                But when you use a own error or exception handler, like xdebug, you
                will get all notices returned, even if this was not your intention.
                This is due to the fact that these handlers override all settings
                from within PHP.
            </para>

            <para>
                To get rid of these notices you can simply set the new option
                'disableNotices' to true. It defaults to false.
            </para>

            <example id="zend.translate.migration.fromonesixtooneseven.example">
                <title>Setting languages without getting notices</title>

                <para>
                    Let's assume that we have 'en' available and our user requests
                    'fr' which is not in our portfolio of translated languages.
                </para>

                <programlisting language="php"><![CDATA[
$language = new Zend_Translate('gettext',
                               '/path/to/translations',
                               'auto');
]]></programlisting>

                <para>
                    In this case we will get an notice about a not available language 'fr'.
                    Simply add the option and the notices will be disabled.
                </para>

                <programlisting language="php"><![CDATA[
$language = new Zend_Translate('gettext',
                               '/path/to/translations',
                               'auto',
                               array('disableNotices' => true));
]]></programlisting>

            </example>

        </sect3>
    </sect2>
</sect1>