Сервис локализации

Сервис локализации (также localizationservice) предназначен для создания, хранения и управления переводами (записями локализации) в словарях.
Запись локализации содержит:

ключ: текстовая строка-идентификатор, позволяющая находить запись локализации;
набор пар «язык – текст перевода»: позволяющие получить текст на выбранном языке.

Словари содержат в себе группы записей локализации. Словари позволяют объединять и изолировать связанные по смыслу записи локализации, для удобной разработки и управления элементами пользовательского интерфейса: названиями кнопок, полей, описания, ошибки и др., переведенными на все или выбранные языки, поддерживающиеся продуктом. Для создания, удаления, изменения словарей и записей локализации используюся административная консоль Платформы, API сервиса или клиентская библиотека ASE.MD.Platform.Infrastructure.Localization.Client на языке C#.

Структуры данных сервиса локализации

Культура (Culture)

Культура (Culture): группа, определяющая языковую принадлежность записей локализации. Набор полей Culture описан в таблице ниже.

Название поля	Тип поля	Описание
ISO	string	уникальный идентификатор культуры в стандарте RFC 5646, максимальная длина поля — 5 символов (2-2, например, ru-RU)
Title	string	описание культуры, максимальная длина поля — 50 символов
Enabled	boolean	признак использования культуры в системе (разрешить или запретить использование)
IsDefault	boolean	признак использования культуры как культуры по умолчанию

к сведению

Культурой по умолчанию может быть только одна культура из списка культур.
Если в настройках браузера пользователя не определена культура, будет отображаться интерфейс с использованием культуры по умолчанию, то есть той культуры, у которой параметр IsDefault принимает значение True.

Словарь (Dictionary)

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

Название поля	Тип поля	Описание
Code	string	уникальный идентификатор словаря, название, максимальная длина поля – 128 символов
Title	string	описание словаря, максимальная длина поля — 64 символа
Enabled	boolean	признак использования словаря в системе (разрешить или запретить использование)
ReadOnly	boolean	Флаг `только для чтения`

предупреждение

Если в поле ReadOnly установлен флаг только для чтения, то изменение словаря невозможно.

Перевод (Translation)

Перевод (Translation) – связка:

ключ: текстовая строка-идентификатор, позволяющая находить запись локализации.
значения: набор пар «язык – текст перевода» позволяющие получить текст на всех языках или на выбранном языке.

Набор полей перевода описан в таблице ниже.

Название поля	Тип поля	Описание
ID	string	внутренний идентификатор перевода, генерируется при создании перевода
Key	string	ключ, максимальная длина поля – 64 символа
Value	string	значения
CultureISO	string	код культуры по RFC 5646
DictionaryСode	string	код словаря, к которому относится перевод
ReadOnly	boolean	Флаг `только для чтения`

ID: внутренний идентификатор перевода, через который возможна работа с Translation, например, получение или удаление Translation в клиентской библиотеке; удаление Translation с помощью ID может потребоваться в случае, если в разных словарях есть одинаковые ключи.

предупреждение

Если в поле ReadOnly установлен флаг только для чтения, то изменение перевода невозможно.

Алгоритм получения перевода

От клиента на сервис локализации приходит запрос на получение выбранной записи локализации.
Запрос осуществляется из определенного словаря по идентификатору DictionaryCode и определенной культуры с идентификатором CultureISO, содержащей нужный перевод.
В качестве результата работы запроса клиенту возвращается значение перевода (запись локализации).

Примеры использования методов API сервиса.

Получение переводов словаря

urn: api/translations/get/bylibrary

Получение переводов словаря

тело запроса:

{
  "dictionaryCode": "string"
}

Модель ответа:

{
  "result": [
    {
      "translate": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "dictionaryCode": "string",
      "key": "string"
    }
  ],
  "error": {
    "message": "string",
    "exceptionType": "string",
    "code": "string",
    "source": "string",
    "inners": [
      {
        "exceptionType": "string",
        "message": "string"
      }
    ],
    "extra": "string",
    "isError": true,
    "id": "string",
    "type": "None"
  }
}

Пример запроса

запрос

{
  "dictionaryCode": "FrontendProject"
}

ответ

{
  "translations": [
    {
      "translate": {
        "ru-RU": "Активные параметры",
        "en-US": "Active parameters"
      },
      "dictionaryCode": "FrontendProject",
      "key": "ActiveParameters"
    },
    {
      "translate": {
        "ru-RU": "Добавить",
        "en-US": "Add"
      },
      "dictionaryCode": "FrontendProject",
      "key": "Add"
    }
	  ],
  "error": {
    "message": "",
    "exceptionType": "",
    "code": "",
    "source": "",
    "inners": [],
    "extra": "",
    "isError": false,
    "id": "",
    "type": "None"
  }
}

Получение перевода слова по словарю и ключу

urn: api/translations/GetbyLibraryandKey

Получение перевода слова по словарю и ключу

тело запроса

{
  "dictionaryCode": "string",
  "key": "string"
}

Модель ответа:

{
  "result": [
    {
      "translate": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "dictionaryCode": "string",
      "key": "string"
    }
  ],
  "error": {
    "message": "string",
    "exceptionType": "string",
    "code": "string",
    "source": "string",
    "inners": [
      {
        "exceptionType": "string",
        "message": "string"
      }
    ],
    "extra": "string",
    "isError": true,
    "id": "string",
    "type": "None"
  }
}

Пример запроса

запрос

{
  "dictionaryCode": "FrontendProject",
  "key": "AddTitle"
}

ответ

{
  "translations": [
    {
      "translate": {
        "en-US": "Create a template",
        "ru-RU": "Создание шаблона"
      },
      "dictionaryCode": "FrontendProject",
      "key": "AddTitle"
    }
  ],
  "result": [
    {
      "translate": {
        "en-US": "Create a template",
        "ru-RU": "Создание шаблона"
      },
      "dictionaryCode": "FrontendProject",
      "key": "AddTitle"
    }
  ],
  "error": {
    "message": "",
    "exceptionType": "",
    "code": "",
    "source": "",
    "inners": [],
    "extra": "",
    "isError": false,
    "id": "",
    "type": "None"
  }
}

Получение всех переводов методом без параметров

urn: api/translations/all

Получение всех переводов методом без параметров

Модель ответа

{
  "result": [
    {
      "id": "string",
      "key": "string",
      "value": "string",
      "cultureISO": "string",
      "dictionaryCode": "string",
      "readOnly": true
    }
  ],
  "error": {
    "message": "string",
    "exceptionType": "string",
    "code": "string",
    "source": "string",
    "inners": [
      {
        "exceptionType": "string",
        "message": "string"
      }
    ],
    "extra": "string",
    "isError": true,
    "id": "string",
    "type": "None"
  }
}

Пример запроса

ответа

{
  "words": [
    {
      "id": "a7b9bb82-f3d4-4b47-a296-1cac7cfd98d9",
      "key": "DPITenantId",
      "value": "Tenant ID",
      "cultureISO": "en-US",
      "dictionaryCode": "FrontendProject",
      "readOnly": false
    },
    {
      "id": "9bd7e289-e611-465b-8f55-64cb065e794e",
      "key": "key1",
      "value": "Ключ один",
      "cultureISO": "ru-RU",
      "dictionaryCode": "12",
      "readOnly": false
    },
    {
      "id": "21fd1c41-fd48-40e6-a2fb-1b61c9395f3f",
      "key": "Карандаш",
      "value": "карандаш",
      "cultureISO": "ru-RU",
      "dictionaryCode": "12",
      "readOnly": false
    }
	  ],
  "error": {
    "message": "",
    "exceptionType": "",
    "code": "",
    "source": "",
    "inners": [],
    "extra": "",
    "isError": false,
    "id": "",
    "type": "None"
  }
}

Получение все переводов в словаре расширенным методом

urn: api/translations/get/bylibrary/ex

Получение всех переводов расширенным методом

Тело запроса

{
  "dictionaryCode": "string"
}

Модель ответа

{
  "info": {
    "dictionaryReadOnly": true,
    "translations": [
      {
        "id": "string",
        "key": "string",
        "value": "string",
        "cultureISO": "string",
        "dictionaryCode": "string",
        "readOnly": true
      }
    ]
  },
  "result": {
    "dictionaryReadOnly": true,
    "translations": [
      {
        "id": "string",
        "key": "string",
        "value": "string",
        "cultureISO": "string",
        "dictionaryCode": "string",
        "readOnly": true
      }
    ]
  },
  "error": {
    "message": "string",
    "exceptionType": "string",
    "code": "string",
    "source": "string",
    "inners": [
      {
        "exceptionType": "string",
        "message": "string"
      }
    ],
    "extra": "string",
    "isError": true,
    "id": "string",
    "type": "None"
  }
}

Пример запроса

Запрос

{
  "dictionaryCode": "FrontendProject"
}

Ответ

{
  "info": {
    "dictionaryReadOnly": false,
    "translations": [
      {
        "id": "b6cbf6ec-c684-4fae-88ac-9172c682624a",
        "key": "ActiveParameters",
        "value": "Активные параметры",
        "cultureISO": "ru-RU",
        "dictionaryCode": "FrontendProject",
        "readOnly": false
      },
      {
        "id": "31044313-92db-43f1-8138-8d286edc9ab2",
        "key": "ActiveParameters",
        "value": "Active parameters",
        "cultureISO": "en-US",
        "dictionaryCode": "FrontendProject",
        "readOnly": false
      },
      {
        "id": "ec85770e-84f0-4663-beb9-0a1400ba776a",
        "key": "Add",
        "value": "Добавить",
        "cultureISO": "ru-RU",
        "dictionaryCode": "FrontendProject",
        "readOnly": false
      }
	      ]
  },
  "error": {
    "message": "",
    "exceptionType": "",
    "code": "",
    "source": "",
    "inners": [],
    "extra": "",
    "isError": false,
    "id": "",
    "type": "None"
  }
}

Получение всех переводов слова в словаре по ключу расширенным методом

urn: api/translations/GetbyLibraryandKeyEx

Получение всех переводов слова в словаре по ключу расширенным методом

Тело запроса:

{
  "dictionaryCode": "string",
  "key": "string"
}

Модель ответа:

{
  "info": {
    "dictionaryReadOnly": true,
    "translations": [
      {
        "id": "string",
        "key": "string",
        "value": "string",
        "cultureISO": "string",
        "dictionaryCode": "string",
        "readOnly": true
      }
    ]
  },
  "result": {
    "dictionaryReadOnly": true,
    "translations": [
      {
        "id": "string",
        "key": "string",
        "value": "string",
        "cultureISO": "string",
        "dictionaryCode": "string",
        "readOnly": true
      }
    ]
  },
  "error": {
    "message": "string",
    "exceptionType": "string",
    "code": "string",
    "source": "string",
    "inners": [
      {
        "exceptionType": "string",
        "message": "string"
      }
    ],
    "extra": "string",
    "isError": true,
    "id": "string",
    "type": "None"
  }
}

Пример запроса

Запрос

{
  "dictionaryCode": "FrontendProject",
  "key": "ActiveParameters"
}

Ответ

{
  "info": {
    "dictionaryReadOnly": false,
    "translations": [
      {
        "id": "31044313-92db-43f1-8138-8d286edc9ab2",
        "key": "ActiveParameters",
        "value": "Active parameters",
        "cultureISO": "en-US",
        "dictionaryCode": "FrontendProject",
        "readOnly": false
      },
      {
        "id": "b6cbf6ec-c684-4fae-88ac-9172c682624a",
        "key": "ActiveParameters",
        "value": "Активные параметры",
        "cultureISO": "ru-RU",
        "dictionaryCode": "FrontendProject",
        "readOnly": false
      }
    ]
  },
  "result": {
    "dictionaryReadOnly": false,
    "translations": [
      {
        "id": "31044313-92db-43f1-8138-8d286edc9ab2",
        "key": "ActiveParameters",
        "value": "Active parameters",
        "cultureISO": "en-US",
        "dictionaryCode": "FrontendProject",
        "readOnly": false
      },
      {
        "id": "b6cbf6ec-c684-4fae-88ac-9172c682624a",
        "key": "ActiveParameters",
        "value": "Активные параметры",
        "cultureISO": "ru-RU",
        "dictionaryCode": "FrontendProject",
        "readOnly": false
      }
    ]
  },
  "error": {
    "message": "",
    "exceptionType": "",
    "code": "",
    "source": "",
    "inners": [],
    "extra": "",
    "isError": false,
    "id": "",
    "type": "None"
  }
}

Добавление переводов слова в словарь

urn: api/translations/AddbyLibrary

Добавление переводов слова в словарь

тело запроса:

{
  "translate": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "dictionaryCode": "string",
  "key": "string"
}

модель ответа:

{
  "message": "string",
  "exceptionType": "string",
  "code": "string",
  "source": "string",
  "inners": [
    {
      "exceptionType": "string",
      "message": "string"
    }
  ],
  "extra": "string",
  "isError": true,
  "id": "string",
  "type": "None"
}

Пример запроса

запрос

{
  "translate": {
    "en-US": "parameters"
  },
  "dictionaryCode": "FrontendProject",
  "key": "Parameters"
}

ответ

{
  "message": "",
  "exceptionType": "",
  "code": "",
  "source": "",
  "inners": [],
  "extra": "",
  "isError": false,
  "id": "",
  "type": "None"
}

Добавление нового перевода слова

urn: api/translations/Add

Добавление нового перевода слова

тело запроса:

{
  "id": "string",
  "key": "string",
  "value": "string",
  "cultureISO": "string",
  "dictionaryCode": "string",
  "readOnly": true
}

модель ответа:

{
  "message": "string",
  "exceptionType": "string",
  "code": "string",
  "source": "string",
  "inners": [
    {
      "exceptionType": "string",
      "message": "string"
    }
  ],
  "extra": "string",
  "isError": true,
  "id": "string",
  "type": "None"
}

Пример запроса

запрос

{
  "id": "4ae74653-b7e6-4134-9fd6-2bb26dfea4f1",
  "key": "test",
  "value": "test",
  "cultureISO": "ru-RU",
  "dictionaryCode": "FrontendProject",
  "readOnly": false
}

ответ

{
  "message": "",
  "exceptionType": "",
  "code": "",
  "source": "",
  "inners": [],
  "extra": "",
  "isError": false,
  "id": "",
  "type": "None"
}

Структуры данных сервиса локализации​

Культура (Culture)​

Словарь (Dictionary)​

Перевод (Translation)​

Алгоритм получения перевода​

Примеры использования методов API сервиса.​

Получение переводов словаря​

Получение перевода слова по словарю и ключу​

Получение всех переводов методом без параметров​

Получение все переводов в словаре расширенным методом​

Получение всех переводов слова в словаре по ключу расширенным методом​

Добавление переводов слова в словарь​

Добавление нового перевода слова​

Структуры данных сервиса локализации

Культура (Culture)

Словарь (Dictionary)

Перевод (Translation)

Алгоритм получения перевода

Примеры использования методов API сервиса.

Получение переводов словаря

Получение перевода слова по словарю и ключу

Получение всех переводов методом без параметров

Получение все переводов в словаре расширенным методом

Получение всех переводов слова в словаре по ключу расширенным методом

Добавление переводов слова в словарь

Добавление нового перевода слова