msgcat

ИМЯ

msgcat — Каталог сообщений Tcl

СИНТАКСИС

ОПИСАНИЕ

КОМАНДЫ

::msgcat::mc строка-источник ?аргумент аргумент ...?

::msgcat::mcmax ?строка-источник строка-источник ...?

::msgcat::mcexists ?-exactnamespace? ?-exactlocale? строка-источник

::msgcat::mclocale ?новый_языковой_стандарт?

::msgcat::mcpreferences

::msgcat:mcloadedlocales подкоманда ?языковой_стандарт?

::msgcat::mcload имя_каталога

::msgcat::mcset языковой_стандарт строка-источник ?строка-перевод?

::msgcat::mcmset языковой_стандарт список_источник-перевод

::msgcat::mcflset строка-источник ?строка-перевод?

::msgcat::mcflmset список_источник-перевод

::msgcat::mcunknown языковой_стандарт строка-источник ?аргумент аргумент ...?

::msgcat::mcforgetpackage

changecmd

unknowncmd

Имя

Синтаксис

Описание

msgcat различает пакеты по их именам пространств имён. Каждый пакет имеет свой собственный каталог сообщений и параметры конфигурации в msgcat.

Языковой стандарт — это строка спецификации, описывающая язык пользователя, например, de_ch для швейцарского немецкого языка. В msgcat существует глобальный языковой стандарт, инициализированный языковым стандартом текущей операционной системы. Каждый пакет может решить использовать глобальный языковой стандарт или использовать специфичный для пакета языковой стандарт.

Глобальный языковой стандарт может быть изменен по запросу, например, пользователем в результате изменения языка или в многопользовательском приложении, например, веб-сервере.

Команды

::msgcat::mc строка-источник ?аргумент аргумент ...?

Возвращает перевод строка-источник в соответствии с текущим языковым стандартом. Если предоставлены дополнительные аргументы после строка-источник, используется команда format для подстановки дополнительных аргументов в перевод строка-источник.

::msgcat::mc будет искать сообщения, определенные в текущем пространстве имён, для перевода строка-источник; если не найдено, будет искать в родительском пространстве имён и так далее, пока не достигнет глобального пространства имён. Если строка перевода не существует, вызывается ::msgcat::mcunknown, и возвращается строка, возвращённая ::msgcat::mcunknown.

::msgcat::mc — основная функция, используемая для локализации приложения. Вместо непосредственного использования английской строки, приложение может передать английскую строку через ::msgcat::mc и использовать результат. Если приложение написано для одного языка таким способом, то легко добавить поддержку дополнительных языков позже, просто определив новые записи в каталоге сообщений.

::msgcat::mcmax ?строка-источник строка-источник ...?

При задании нескольких строк-источников ::msgcat::mcmax возвращает длину самой длинной переведенной строки. Это полезно при проектировании локализованных пользовательских интерфейсов, где, например, все кнопки должны иметь фиксированную ширину (равную ширине самой широкой кнопки).

::msgcat::mcexists ?-exactnamespace? ?-exactlocale? строка-источник

Возвращает true, если для данной строка-источник есть перевод.

Поиск может быть ограничен опцией -exactnamespace, чтобы проверить только текущее пространство имен, а не родительские пространства имён.

Также он может быть ограничен опцией -exactlocale, чтобы проверить только первый предпочтительный языковой стандарт (например, первый элемент, возвращённый ::msgcat::mcpreferences, если используется глобальный языковой стандарт).

::msgcat::mclocale ?новый_языковой_стандарт?

Эта функция устанавливает языковой стандарт на новый_языковой_стандарт. Если новый_языковой_стандарт опущено, возвращается текущий языковой стандарт, в противном случае текущий языковой стандарт устанавливается на новый_языковой_стандарт. msgcat хранит и сравнивает языковой стандарт без учёта регистра и возвращает языковые стандарты в нижнем регистре. Изначальный языковой стандарт определяется языковым стандартом, указанным в среде пользователя. См. СПЕЦИФИКАЦИЮ ЯЗЫКОВОГО СТАНДАРТА ниже для описания формата строки языкового стандарта.

Если языковой стандарт установлен, оценивается список предпочтительных языковых стандартов. Языковые стандарты в этом списке загружаются сейчас, если еще не загружены.

::msgcat::mcpreferences

Возвращает упорядоченный список языковых стандартов, предпочтительных для пользователя, на основе спецификации языка пользователя. Список упорядочен от наиболее предпочтительного к наименее предпочтительному. Список получен из текущего языкового стандарта, установленного в msgcat командой ::msgcat::mclocale, и не может быть установлен независимо. Например, если текущий языковой стандарт — en_US_funky, то ::msgcat::mcpreferences возвращает {en_us_funky en_us en {}}.

::msgcat:mcloadedlocales подкоманда ?языковой_стандарт?

Эта группа команд управляет списком загруженных языковых стандартов для пакетов, которые не устанавливают языковой стандарт пакета.

Подкоманда get возвращает список текущих загруженных языковых стандартов.

Подкоманда present требует аргумент языковой_стандарт и возвращает true, если этот языковой стандарт загружен.

Подкоманда clear удаляет все языковые стандарты и их данные, которые не находятся в текущем списке предпочтений.

::msgcat::mcload dirname

Ищет в указанном каталоге файлы, которые соответствуют языковым спецификациям, возвращаемым функцией ::msgcat::mcloadedlocales get (или msgcat::mcpackagelocale preferences, если установлен пакетный локаль) (обратите внимание, что все они в нижнем регистре), расширенные расширением файла ".msg". Каждый соответствующий файл читается в порядке, предполагая кодировку UTF-8. Затем содержимое файла обрабатывается как скрипт Tcl. Это означает, что символы Юникода могут присутствовать в файле сообщений либо напрямую в их кодировке UTF-8, либо с использованием обратного слэша-u, распознаваемого Tcl. Возвращается количество файлов сообщений, которые соответствовали спецификации и были загружены.

Кроме того, данный каталог сохраняется в параметре конфигурации пакета msgcat mcfolder для последующей загрузки файлов каталога сообщений, необходимых для изменения локали.

::msgcat::mcset locale src-string ?translate-string?

Устанавливает перевод для src-string на translate-string в указанной locale и текущем пространстве имен. Если translate-string не указан, используется src-string для обоих значений. Функция возвращает translate-string.

::msgcat::mcmset locale src-trans-list

Устанавливает перевод для нескольких исходных строк в src-trans-list в указанной locale и текущем пространстве имен. src-trans-list должен иметь четное количество элементов и иметь вид {src-string translate-string ?src-string translate-string ...?}. ::msgcat::mcmset может быть значительно быстрее, чем несколько вызовов ::msgcat::mcset. Функция возвращает количество установленных переводов.

::msgcat::mcflset src-string ?translate-string?

Устанавливает перевод для src-string на translate-string в текущем пространстве имен для локали, подразумеваемой именем каталога сообщений, загружаемого через ::msgcat::mcload. Если translate-string не указан, используется src-string для обоих значений. Функция возвращает translate-string.

::msgcat::mcflmset src-trans-list

Устанавливает перевод для нескольких исходных строк в src-trans-list в текущем пространстве имен для локали, подразумеваемой именем каталога сообщений, загружаемого через ::msgcat::mcload. src-trans-list должен иметь четное количество элементов и иметь вид {src-string translate-string ?src-string translate-string ...?}. ::msgcat::mcflmset может быть значительно быстрее, чем несколько вызовов ::msgcat::mcflset. Функция возвращает количество установленных переводов.

::msgcat::mcunknown locale src-string ?arg arg ...?

Эта процедура вызывается ::msgcat::mc в случае, если перевод для src-string не определен в текущей локали. По умолчанию возвращается src-string, переданный в формате, если есть какие-либо аргументы. Эту процедуру можно переопределить приложением, например, для записи сообщений об ошибках для каждой неизвестной строки. Процедура ::msgcat::mcunknown вызывается в том же контексте стека, что и вызов ::msgcat::mc. Возвращаемое значение ::msgcat::mcunknown используется как возвращаемое значение для вызова ::msgcat::mc.

Обратите внимание, что эта процедура вызывается только в том случае, если соответствующий пакет не задал имя команды неизвестной локали пакета.

::msgcat::mcforgetpackage

Вызывающий пакет очищает все свои состояния в пакете msgcat, включая все настройки и переводы.

Спецификация локали

При первой загрузке пакета msgcat локаль инициализируется в соответствии со средой пользователя. Переменные env(LC_ALL), env(LC_MESSAGES) и env(LANG) проверяются в указанном порядке. Первая из них, имеющая ненулевое значение, используется для определения начальной локали. Значение анализируется по шаблону XPG4

language[_country][.codeset][@modifier]

для извлечения его частей. Затем начальная локаль устанавливается путем вызова ::msgcat::mclocale с аргументом

language[_country][_modifier]

В Windows и Cygwin, если ни одна из этих переменных среды не задана, msgcat попытается извлечь информацию о локали из реестра. Начиная с Windows Vista, имя локали RFC4747 "lang-script-country-options" преобразуется в локаль как "lang_country_script" (Пример: sr-Latn-CS -> sr_cs_latin). Для Windows XP идентификатор языка преобразуется аналогичным образом (Пример: 0c1a -> sr_yu_cyrillic). Если все эти попытки обнаружить начальную локаль из среды пользователя не увенчаются успехом, msgcat по умолчанию использует начальную локаль «C».

Когда локаль задается пользователем, во время перевода строки выполняется поиск «лучшего соответствия». Например, если пользователь указывает en_GB_Funky, ищутся локали «en_gb_funky», «en_gb», «en» и «» (пустая строка) в указанном порядке, пока не будет найдена соответствующая строка перевода. Если строка перевода недоступна, вызывается обработчик неизвестных значений.

Пространства имен и каталоги сообщений

Например, выполнение кода

::msgcat::mcset en hello "hello from ::"
namespace eval foo {
    ::msgcat::mcset en hello "hello from ::foo"
}
puts [::msgcat::mc hello]
namespace eval foo {puts [::msgcat::mc hello]}

выведет

hello from ::
hello from ::foo

При поиске перевода сообщения каталог сообщений сначала ищет текущее пространство имен, затем родительское пространство имен и так далее, пока не достигнет глобального пространства имен. Это позволяет дочерним пространствам имен «наследовать» сообщения из родительского пространства имен.

Например, выполнение (в локали «en») кода

::msgcat::mcset en m1 ":: message1"
::msgcat::mcset en m2 ":: message2"
::msgcat::mcset en m3 ":: message3"
namespace eval ::foo {
    ::msgcat::mcset en m2 "::foo message2"
    ::msgcat::mcset en m3 "::foo message3"
}
namespace eval ::foo::bar {
    ::msgcat::mcset en m3 "::foo::bar message3"
}
namespace import ::msgcat::mc
puts "[mc m1]; [mc m2]; [mc m3]"
namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc m3]"}
namespace eval ::foo::bar {puts "[mc m1]; [mc m2]; [mc m3]"}

выведет

:: message1; :: message2; :: message3
:: message1; ::foo message2; ::foo message3
:: message1; ::foo message2; ::foo::bar message3

Расположение и формат файлов сообщений

1. Все файлы сообщений для пакета находятся в одном каталоге.
2. Имя файла сообщений — спецификатор локали msgcat (все строчные буквы), за которым следует «.msg». Например:

es.msg    — spanish
en_gb.msg — United Kingdom English

Исключение: Файл сообщения для корневой локали «» называется «ROOT.msg». Это исключение сделано, чтобы не вызвать необычное поведение, например, пометить файл сообщения как «скрытый» в файловых системах Unix.

3. Файл содержит ряд вызовов mcflset и mcflmset, устанавливающих необходимые строки перевода для языка, скорее всего, заключенные в namespace eval, чтобы все исходные строки были привязаны к пространству имен пакета. Например, короткий файл es.msg может содержать:

namespace eval ::mypackage {
    ::msgcat::mcflset "Free Beer" "Cerveza Gratis"
}

Рекомендованная настройка сообщений для пакетов

1. При установке пакета создайте подкаталог msgs в каталоге вашего пакета.
2. Скопируйте ваши файлы *.msg в этот каталог.
3. Добавьте следующую команду в скрипт инициализации пакета:

# load language files, stored in msgs subdirectory
::msgcat::mcload [file join [file dirname [info script]] msgs]

Позиционные коды для команд format и scan

format "We produced %d units in location %s" $num $city
format "In location %s we produced %d units" $city $num

Это можно сделать, используя позиционные параметры:

format "We produced %1\$d units in location %2\$s" $num $city
format "In location %2\$s we produced %1\$d units" $num $city

Аналогично, позиционные параметры могут использоваться с scan для извлечения значений из интернационализированных строк. Обратите внимание, что не обязательно передавать результат ::msgcat::mc в format напрямую; передавая значения для подстановки в качестве аргументов, подстановка формата выполняется непосредственно.

msgcat::mc {Produced %1$d at %2$s} $num $city
# ... where that key is mapped to one of the
# human-oriented versions by msgcat::mcset

Локаль, частная для пакета

Это позволяет пакету изменять свою локаль, не вызывая загрузки или удаления локалей в других пакетах и не вызывая обратного вызова изменения глобальной локали (см. ниже).

Данное действие контролируется следующим набором команд:

::msgcat::mcpackagelocale set ?locale?

Установить или изменить локаль, частную для пакета. Локаль, частная для пакета, устанавливается в заданную locale, если locale указана. Если параметр locale не указан, пакет переводится в режим использования частной локали, но локаль не изменяется (например, если глобальная локаль была допустима для пакета до этого, она копируется в локаль, частную для пакета).

Эта команда может вызвать загрузку локалей.

::msgcat::mcpackagelocale get

Возвращает локаль, частную для пакета, или глобальную локаль, если локали, частной для пакета, нет.

::msgcat::mcpackagelocale preferences

Возвращает предпочтения, частные для пакета, или глобальные предпочтения, если предпочтений, частных для пакета, нет.

::msgcat::mcpackagelocale loaded

Возвращает список загруженных локалей для этого пакета.

::msgcat::mcpackagelocale isset

Возвращает true, если локали, частной для пакета, установлена.

::msgcat::mcpackagelocale unset

Сбросить локаль, частную для пакета, и использовать глобальную локаль. Загрузить и удалить локали, чтобы скорректировать список загруженных локалей для пакета до списка загруженных глобальных локалей.

::msgcat::mcpackagelocale present locale

Возвращает true, если указанная локаль загружена для пакета.

::msgcat::mcpackagelocale clear

Очистить любые загруженные локали пакета, отсутствующие в предпочтениях пакета.

Изменение параметров пакета

::msgcat::mcpackageconfig get option

Возвращает текущее значение заданного option. Этот вызов возвращает ошибку, если параметр не установлен для пакета.

::msgcat::mcpackageconfig isset option

Возвращает 1, если заданный option установлен для пакета, и 0 в противном случае.

::msgcat::mcpackageconfig set option value

Устанавливает заданный option в заданное value. Это может вызвать дополнительные действия в зависимости от option. Значение возврата — 0 или количество загруженных пакетов для параметра mcfolder.

::msgcat::mcpackageconfig unset option

Снимает установку заданного option для пакета. Если option не установлен для пакета, никаких действий не выполняется. Возвращается пустая строка.

Параметры пакета

mcfolder

Это папка сообщений пакета. Этот параметр устанавливается mcload и подкомандой set. Оба одинаковы и оба возвращают количество загруженных файлов каталога сообщений.

Изменение этого значения загрузит все языковые локали, содержащиеся в настройках, действительных для пакета. Это также подразумевает вызов любого установленного loadcmd (см. ниже).

Снятие установки этого значения отключит загрузку файлов сообщений для пакета.

loadcmd

Этот обратный вызов вызывается перед загрузкой набора файлов каталога сообщений для пакета, у которого установлен этот параметр.

Этот обратный вызов можно использовать для выполнения любой подготовительной работы для загрузки файла сообщений или для получения данных сообщений из другого источника, например, базы данных. В этом случае файлы сообщений не используются (mcfolder снят с установки).

См. раздел вызов обратного вызова ниже. Список параметров, добавленный к этому обратному вызову, — это список локалей для загрузки.

Если этот обратный вызов изменен, он вызывается с настройками, действительными для пакета.

changecmd

Этот обратный вызов вызывается при выполнении изменения по умолчанию локали. Его цель — позволить пакету обновить любые зависимости от локали по умолчанию, например, отобразить графический интерфейс на другом языке.

См. раздел вызова обратного вызова ниже. Список параметров, добавленный к этому обратному вызову, — mcpreferences. Зарегистрированные обратные вызовы вызываются в произвольном порядке.

unknowncmd

Используйте процедуру mcunknown для локали пакета вместо стандартной версии, предоставляемой пакетом msgcat (msgcat::mcunknown).

Вызываемая процедура должна вернуть отформатированное сообщение, которое в конечном итоге будет возвращено msgcat::mc.

Если значение установлено в пустую строку, используется общий обработчик неизвестных. Он состоит в возвращении ключа, если аргументы не заданы. При наличии аргументов используется функция format для обработки аргументов.

См. раздел вызов обратного вызова ниже. Аргументы, добавленные к нему, идентичны ::msgcat::mcunknown.

Вызов обратного вызова

Обратные вызовы вызываются, если:

1. команда обратного вызова установлена,

2. команда не пустая строка,

3. пространство имен регистрации существует.

Если вызываемая процедура завершается с ошибкой, процедура bgerror для интерпретатора вызывается после завершения команды. Исключением является обратный вызов unknowncmd, где ошибка приводит к тому, что вызывающая команда mc завершается с этой ошибкой.

Примеры

namespace eval gui {
    msgcat::mcpackageconfig changecmd updateGUI

    proc updateGui args {
        puts "New locale is '[lindex $args 0]'."
    }
}
% msgcat::mclocale fr
fr
% New locale is 'fr'.

Если локали (или дополнительные локали) содержатся в другом источнике, например, базе данных, пакет может использовать обратный вызов загрузки, а не mcload:

namespace eval db {
    msgcat::mcpackageconfig loadcmd loadMessages

    proc loadMessages args {
        foreach locale $args {
            if {[LocaleInDB $locale]} {
                msgcat::mcmset $locale [GetLocaleList $locale]
            }
        }
    }
}

Реализация команды clock использует msgcat с локалью пакета для реализации параметра командной строки -locale. Вот некоторые наброски реализации:

Сначала инициализируется локаль пакета, и общая функция unknown деактивируется:

msgcat::mcpackagelocale set
msgcat::mcpackageconfig unknowncmd ""

clock format clock seconds -format %A -locale fr

msgcat::mcpackagelocale set $locale
return [lindex [msgcat::mc DAYS_OF_WEEK_FULL] $day]
### Returns "mercredi"

proc ::tcl::clock::LocalizeFormat { locale format } {
    set key FORMAT_$format
    if { [::msgcat::mcexists -exactlocale -exactnamespace $key] } {
        return [mc $key]
    }
    #...expensive computation of format clipped...
    mcset $locale $key $format
    return $format
}

Авторы

См. также