Локализация приложений
**********************

Jandcode поддерживает локализацию приложений, основанную на переводе строковых констант.
Идея в том, что все строковые ресурсы проекта, которые в будующем потребуется перевести,
пишутся в проекте на одном языке (в текущей реализации - на русском). В исходных
текстах такие строки оборачиваются в вызов метода ``UtLang.t`` (для java, groovy, gsp, javascript).

.. code-block:: java

    // обычная строка
    System.out("Привет!");
    // переводимая строка
    System.out(UtLang.t("Привет!"));

С помощью средств, предоставляемых утилитой ``jc``, переводимые строки можно извлечь
в специальные файлы, перевести и таким образом обеспечить поддержку нового языка.
Строки, для которых не был предоставлен перевод, будут представлены оригинальным
текстом на языке по умолчанию (в текущей реализации - на русском).

Настройка project.jc
====================

В project.jc нужно подключить модуль поддержки локализации:

.. code-block:: java

    include "localize-project"

После подключения будут доступны новые команды::

    lang-check
    lang-grab
    lang-update


Выявление строк для перевода
============================

Запускаем::

    jc lang-check

Эта команда анализирует исходные тексты и выявляет строки, которые никак не помечены
для локализации в исходниках. Все строки собираются в файл ``temp\lang-check.txt``.
Для каждой строки указывается сама строка и место в файле, в котором она обнаружена.

Каждую константу, требующую перевода, необходимо обернуть в вызов функции ``UtLang.t``.
Например было:

.. code-block:: java

    String s = "Привет";  // java
    var s = "Привет";     // javascript

Должно стать:

.. code-block:: java

    String s = UtLang.t("Привет"); //java
    var s = UtLang.t("Привет");        //javascript

Если строка описана как константа, то переводит ее нужно в месте использования!

.. code-block:: java

    class Test {
		public static String AA = "Привет"; //NLS
		void getAA() {
			return UtLang.t(AA);
		}
	}

Константы, требующие перевода, но не заключенные в вызов ``UtLang.t``, можно
пометить коментарием ``//NLS``. Коментарий должен быть указан либо на той же
строке, что и константа, либо перед ней:

.. code-block:: java

    //NLS
    String s = "Привет";

    String s2 = "Привет"; //NLS


Константы, не требующие перевода, нужно пометить коментарием ``//NON-NLS``.
Коментарий должен быть указан либо на той же строке, что и константа, либо перед ней:

.. code-block:: java

    //NON-NLS
    String s = "Привет";

    String s2 = "Привет"; //NON-NLS

Констаны, собранные через "+" нужно объеденить и использовать формат строки из
метода ``MessageFormat.format``:

.. code-block:: java

    // было
    String s = "Обработатано " + n + " файлов";

    // нужно
    String s = UtLang.t("Обработано {0} файлов", n);


Сбор строк для перевода
=======================

После того, как все нужные строки помечены в исходниках, можно собрать их.
Для этого предназначена команда::

    jc lang-grab

Команда пересоздает файл ``lang-data.xml`` в корневом пакете модуля. Файл выглядет так:

.. code-block:: xml

    <?xml version="1.0" encoding="utf-8"?>
    <root>
        <i>
            <s>Добавить</s>
        </i>
        <i>
            <s>Закрыть</s>
        </i>
        <i>
            <s>Назад</s>
        </i>
    </root>

Обновление файла перевода
=========================

После того, как все нужные строки собраны, можно формировать файлы для перевода.
Для этого скопируйте файл ``lang-data.xml`` в тот же каталог с именем ``lang-data-XX.xml``,
где вместо ``XX`` поставьте код языка, для которого этот файл (например ``lang-data-en.xml``).
После этого выполните команду::

    jc lang-update

Получим такой файл:

.. code-block:: xml

    <?xml version="1.0" encoding="utf-8"?>
    <root>
        <i translated="false">
            <s>Добавить</s>
            <t></t>
        </i>
        <i translated="false">
            <s>Закрыть</s>
            <t></t>
        </i>
        <i translated="false">
            <s>Назад</s>
            <t></t>
        </i>
    </root>


Редактируем файл ``lang-data-en.xml``, в теги ``t`` записываем перевод. Снова запускаем
``jc lang-update`` (для убирания пометок о непереведенны строках).

Если в файле ``lang-data.xml`` появятся новые строки, то после выполнения ``jc lang-update``,
эти новые строки попадут во все файлы перевода.