Доработано описание работы методов/полей

proto/items/items.proto

@@ -87,13 +87,13 @@ message Item {
   // Для удаления переводов реализована следующая логика:
   // - {"lang":nil|{}} - сброс перевода для языка
   // - {"lang":map{...}} - установка перевода для языка
-  // - {"lang":map{...}, "*":nil} - установка перевода для языка, сброс остальных переводов
+  // - {"lang":map{...}, "*":nil} - установка перевода для языка (одного или нескольких), сброс остальных переводов
   // - {"*":nil} - сброс всех переводов
   map<string, google.protobuf.Struct> translations = 12;
 
   // Список идентификаторов локалей, для которых есть переводы
-  // Соотвествует списку переводов в translations, при получении записи всегда возвращается
-  // полный список. Невозможно обновить вручную: формируется системой
+  // Соответствует списку переводов в translations, при получении записи всегда возвращается
+  // полный список. Невозможно обновить вручную, формируется системой
   repeated string translations_ids = 101;
 }
 
@@ -152,7 +152,12 @@ message FindOptions {
   bool regular = 4;
   bool hidden = 5;
   bool templates = 6;
-  string locale_id = 7; // Язык перевода который будет использоваться. Если не указан, то возвращаются данные для языка по умолчанию
+
+  // Язык перевода, для которого нужно выполнить запрос. По умолчанию если перевод для запрашиваемого
+  // поля не существует, то поиск проходит по fallback-языку (если указан и существует) или по основным данным.
+  //
+  // Если не указан, то возвращаются данные для языка по умолчанию
+  string locale_id = 7;
 
   // Список идентификаторов переводов/локалей, которых должны быть включены в результат
   // Возможно указание '*' для получения всех переводов

proto/locales/locales.proto

@@ -6,15 +6,33 @@ option go_package = "git.perx.ru/perxis/perxis-go/proto/locales;locales";
 
 package content.locales;
 
+// Locale содержит информацию и настройки для языка
 message Locale {
-  string id = 1; // Идентификатор локали, генерируется автоматически. Для локали по умолчанию устанавливается как "default".
-  string space_id = 2; // Идентификатор пространства.
-  string name = 3; // Название локали. Опционально, заполняется автоматически (Пример: russian, english)
-  string native_name = 4; // Название локали на языке локали. Опционально, заполняется автоматически  (Пример: Русский, English)
-  string code = 5; // Код локали https://en.wikipedia.org/wiki/IETF_language_tag
-  string fallback = 6; // Идентификатор локали, который будет использоваться при отсутствии перевода
+  // Идентификатор локали, генерируется автоматически.
+  //
+  // В пространстве всегда существует одна локаль по умолчанию, для нее идентификатор устанавливается `default`.
+  // `default`-локаль содержит настройки основных данных записи. Ее нельзя удалить, сделать `no_publish` или `disabled`
+  // и для нее нельзя установить `fallback`-локаль.
+  string id = 1;
+
+  // Идентификатор пространства локали.
+  string space_id = 2;
+
+  // Название локали. Опционально: заполняется автоматически, если не было передано (Пример: russian, english)
+  string name = 3;
+
+  // Название локали на языке локали. Опционально, заполняется автоматически  (Пример: Русский, English)
+  string native_name = 4;
+
+  // Код локали https://en.wikipedia.org/wiki/IETF_language_tag. Не является уникальным
+  string code = 5;
+
+  // Идентификатор локали, который будет использоваться при отсутствии перевода. Допускаются цепочки, но при
+  // получении перевода будут использованы только данные основной, fallback и запрошенной локали. Не допускается
+  // кольцевая зависимость локалей.
+  string fallback = 6;
   string direction = 7; // Направление письма - слева направо (ltr) или справа налево (rtl). По умолчанию устанавливается ltr.
-  int64 weight = 8; // Вес локали.
+  int64 weight = 8; // Вес локали. Чем больше, тем ниже приоритет
 
   bool no_publish = 100; // Не публиковать контент данной локали. Не будет доступен контент через Delivery API. (кроме default)
   bool disabled = 101; // Запретить использование локали. Нельзя создавать и редактировать контент для данной локали (кроме default)
@@ -51,7 +69,8 @@ service Locales {
   // Обновить локаль
   rpc Update(UpdateRequest) returns(google.protobuf.Empty) {}
 
-  // Получить список локалей
+  // Получить список локалей. В пространстве всегда есть одна локаль по умолчанию.
+  // Результат возвращается с сортировкой по [ weight, name ]
   rpc List(ListRequest) returns(ListResponse) {}
 
   // Удалить локаль