Интерфейсные тексты в коде: требования по локализации

#std761

Область применения: управляемое приложение, мобильное приложение, обычное приложение.

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

Для этого необходимо применять функцию НСтр вместо прямого использования строковых литералов. Иное использование строк, предназначенных для пользовательского интерфейса, не допускается.

Например, неправильно:

ПоказатьПредупреждение(, "Для выполнения операции необходимо установить расширение работы с файлами.");

Правильно:

ПоказатьПредупреждение(, НСтр("ru='Для выполнения операции необходимо установить расширение работы с файлами.'"));

Также следует обращать внимание на корректное использование функции НСтр.

Например, неправильно:

ТекстСообщения = "ru='Для выполнения операции необходимо установить расширение работы с файлами.'";
ПоказатьПредупреждение(, НСтр(ТекстСообщения));

Правильно:

ТекстСообщения = НСтр("ru='Для выполнения операции необходимо установить расширение работы с файлами.'");
ПоказатьПредупреждение(, ТекстСообщения);

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

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

Неправильно:

СообщениеОНехватке = "Не хватает товара " + НаименованиеТовара + " на складе " + НаименованиеСклада + ".";

Правильно:

ТекстСообщения = НСтр("ru = 'Не хватает товара %1 на складе %2.'");
СообщениеОНехватке = СтрШаблон(ТекстСообщения, НаименованиеТовара, НаименованиеСклада);

Также с помощью параметров подстановки не следует разрывать целостную фразу на отдельные логически незавершенные части. Вместо этого следует задавать в коде несколько строк со всеми вариантами фразы.

Неправильно:

НСтр("ru = '%1 пользователя ""%2"" в группу ""%3""?'") // где параметр %1 может принимать слова "Включить", "Копировать" или "Удалить".

Правильно:

НСтр("ru = 'Включить пользователя ""%2"" в группу ""%3""?'")
НСтр("ru = 'Копировать пользователя ""%2"" в группу ""%3""?'")
НСтр("ru = 'Удалить пользователя ""%2"" из группы ""%3""?'")

В то же время допустимым является:

  1. Составление текста из нескольких предложений (каждое из которых заключено в НСтр и переводится отдельно).
  2. Предложения, заканчивающиеся двоеточием. Например, НСтр("ru = 'Создание каталога не выполнено по причине:'").

В связи со сложившейся практикой, допускается использовать именованные параметры подстановки (параметры, включающие имя аналогично переменной, а не номер) только в двух вариантах: [Параметр], %Параметр%. Здесь Параметр должен удовлетворять требованиям стандарта Правила образования имен переменных.

Правильно:

СообщениеОНехватке = НСтр("ru='Не хватает товара %Товар% на складе %Склад%.'") 
СообщениеОНехватке = СтрЗаменить(СообщениеОНехватке, "%Товар%", НаименованиеТовара); 
СообщениеОНехватке = СтрЗаменить(СообщениеОНехватке, "%Склад%", НаименованиеСклада);

3. При использовании в конфигурации Библиотеки стандартных подсистем для составных форматированных строк вместо объекта ФорматированнаяСтрока следует применять функцию ФорматированнаяСтрока общих модулей СтроковыеФункции или СтроковыеФункцииКлиент.

Неправильно:

Текст = Новый Массив;
Текст.Добавить(НСтр("ru = 'Перед удалением расширения рекомендуется'"));
Текст.Добавить(" ");
Текст.Добавить(Новый ФорматированнаяСтрока(НСтр("ru = 'выполнить резервное копирование информационной базы.'"), ШрифтыСтиля.ПолужирныйШрифт);
ТекстПредупреждения = Новый ФорматированнаяСтрока(Текст);

Правильно:

ТекстПредупреждения = СтроковыеФункцииКлиент.ФорматированнаяСтрока(НСтр("ru = 'Перед удалением расширения рекомендуется <b>выполнить резервное копирование информационной базы</b>.'");

4. В функции НСтр строка ограничивается символами одинарных кавычек. Такое требование обусловлено частым использованием двойных кавычек в строковых литералах, а также встроенным в платформу механизмом редактирования строк на разных языках.

Неправильно:

ПоказатьПредупреждение(, НСтр("ru=Переменная типа ""Строка""")); 
ПоказатьПредупреждение(, НСтр("ru=""Переменная типа ""Строка"""""));

Правильно:

ПоказатьПредупреждение(, НСтр("ru='Переменная типа ""Строка""'"));

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

Например, неправильно:

СообщениеОшибка = НСтр("ru='Обнаружены отрицательные остатки по регистру ТоварыОрганизаций.'");

Правильно:

СообщениеОшибка = СтрШаблон(НСтр("ru = 'Обнаружены отрицательные остатки по регистру ""%1"".'"), Метаданные.РегистрыНакопления.ТоварыОрганизаций.Представление());

Или сокращенный вариант:

СообщениеОшибка = СтрШаблон(НСтр("ru = 'Обнаружены отрицательные остатки по регистру ""%1"".'"), Метаданные.РегистрыНакопления.ТоварыОрганизаций);

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

Неправильно:

СообщениеОшибка = НСтр("ru = 'Ошибка в функции ЕстьРоль модуля УправлениеДоступом.'");

Правильно:

ИмяФункции = "УправлениеДоступом.ЕстьРоль";
СообщениеОшибка = СтрШаблон(НСтр("ru = 'Ошибка в функции %1.'"), ИмяФункции);

Пример для модуля менеджера:

ИмяФункции = "Документы.АвансовыйОтчет.АдаптированныйТекстЗапросаДвиженийПоРегистру";
СообщениеОшибка = СтрШаблон(НСтр("ru = 'Для исправления движений документа необходимо вызвать функцию %1.'"), ИмяФункции);

При выводе имен объектов метаданных рекомендуется получать их напрямую из метаданных с помощью функции ПолноеИмя. Это исключит ошибки перевода, когда переводчики могут пытаться переводить заранее непереводимые имена объектов метаданных и внутренних идентификаторов.

Например, неправильно:

СообщениеОшибка = НСтр("ru='Подсистема некорректно встроена в регистр ТоварыОрганизаций.'");

Правильно:

СообщениеОшибка = СтрШаблон(НСтр("ru = 'Подсистема некорректно встроена в регистр %1.'"), Метаданные.РегистрыНакопления.ТоварыОрганизаций.ПолноеИмя());

6. При использовании функций ЧислоПрописью, ПредставлениеПериода, СтрокаСЧислом не следует указывать параметр "Л="("L=") в строке форматирования.
Например, неправильно:

СуммаПрописью = ЧислоПрописью(2341.56, "Л = ru_RU; ДП = Истина", НСтр("ru='доллар,доллара,долларов,м,цент,цента,центов,м,2'"));

Правильно:

СуммаПрописью = ЧислоПрописью(2341.56, "ДП = Истина", НСтр("ru='доллар,доллара,долларов,м,цент,цента,центов,м,2'"));

7. Недопустимо вызывать функцию ПолучитьСклоненияСтрокиПоЧислу, т.к. она предназначена только для русскоязычного интерфейса. Вместо нее следует использовать специализированные функции:

или реализовывать собственные прикладные функции.

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

Неправильно:

ТекстСообщения = НСтр("ru = 'Не удалось сохранить файл документа по причине:
  |'")
  + ИнформацияОбОшибке;

Правильно:

ТекстСообщения = НСтр("ru = 'Не удалось сохранить файл документа по причине:'")
  + Символы.ПС + ИнформацияОбОшибке;

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

9. При вызове метода ПоказатьВопрос с указанием кнопок диалога в параметре Кнопки:

Например, неправильно:

Кнопки = Новый СписокЗначений;
Кнопки.Добавить("Отключить");
Кнопки.Добавить("Нет");
ПоказатьВопрос(..., Кнопки);

Правильно:

Кнопки = Новый СписокЗначений;
Кнопки.Добавить("Отключить", НСтр("ru='Отключить'"));
Кнопки.Добавить(КодВозвратаДиалога.Нет);
ПоказатьВопрос(..., Кнопки);

См. также