Platform.I18n.Sdk 1.0.1

Platform.I18n.Sdk

SDK для генерации и валидации ключей локализации в соответствии со стандартами платформы Steos.

Описание

Platform.I18n.Sdk — это библиотека, которая обеспечивает единообразную генерацию ключей локализации для интеграции микросервисов с централизованной системой переводов (Translation Service). SDK гарантирует стандартизацию формата ключей, выполняет строгую валидацию входных данных и предотвращает ошибки на ранних этапах разработки.

Установка

Через Package Manager Console

Install-Package Platform.I18n.Sdk -Version 1.0.0

Через .NET CLI

dotnet add package Platform.I18n.Sdk --version 1.0.0

Через PackageReference

<PackageReference Include="Platform.I18n.Sdk" Version="1.0.0" />

Быстрый старт

1. Инициализация

Создайте экземпляр LocalizationKeyGenerator, передав системное имя вашего микросервиса:

using Platform.I18n.Sdk;

// Инициализация для микросервиса "hr"
var keyGenerator = new LocalizationKeyGenerator("hr");

// Регистрация в DI-контейнере (например, в Program.cs)
builder.Services.AddSingleton(keyGenerator);

Важно: Имя микросервиса должно соответствовать формату: ^[a-z][a-z0-9_]{1,30}$ (начинается с маленькой буквы, содержит только маленькие буквы, цифры и подчеркивание, длина от 2 до 31 символа).

2. Генерация ключей для справочников

Используйте метод ForReference для системных справочников (reference data):

// Генерация ключа для профессии "Software Engineer"
string professionKey = keyGenerator.ForReference(
    domain: "hr",           // Предметная область (обычно имя микросервиса)
    concept: "profession",   // Логическое имя сущности
    code: "software_engineer" // Стабильный бизнес-код
);

// Результат: "hr:profession:software_engineer"

3. Генерация ключей для пользовательского контента

Используйте метод ForUserContent для динамического контента, создаваемого пользователями:

// С UUID
string postTitleKey = keyGenerator.ForUserContent(
    entityType: "post",                                    // Тип сущности
    entityId: "550e8400-e29b-41d4-a716-446655440000",    // UUID записи
    fieldName: "title"                                     // Имя поля
);

// Результат: "hr:post:550e8400-e29b-41d4-a716-446655440000:title"

// С бизнес-ID
string articleKey = keyGenerator.ForUserContent(
    entityType: "article",
    entityId: "article-12345",  // Бизнес-ID (буквы, цифры, '-', '_', до 64 символов)
    fieldName: "content"
);

// Результат: "hr:article:article-12345:content"

4. Валидация ключей

Для проверки ключей, полученных извне, используйте статический метод ValidateKey:

// Валидация ключа справочника
bool isValid = LocalizationKeyGenerator.ValidateKey("hr:profession:software_engineer");
// → true

// Валидация ключа пользовательского контента
bool isAlsoValid = LocalizationKeyGenerator.ValidateKey("hr:post:550e8400-e29b-41d4-a716-446655440000:title");
// → true

// Неверный ключ
bool isInvalid = LocalizationKeyGenerator.ValidateKey("invalid-key");
// → false

API Документация

LocalizationKeyGenerator

Конструктор

public LocalizationKeyGenerator(string microserviceName)

Параметры:

• microserviceName — системное имя микросервиса (например, "hr", "blog")

Исключения:

• ArgumentException — если имя микросервиса null, пустое или имеет неверный формат

ForReference

Генерирует ключ локализации для системного справочника.

public string ForReference(string domain, string concept, string code)

Параметры:

• domain — предметная область (обычно имя микросервиса)
• concept — логическое имя сущности (например, "profession")
• code — стабильный бизнес-код сущности (например, "software_engineer")

Возвращает: Строку в формате {domain}:{concept}:{code}

Исключения:

• ArgumentException — если любой из параметров имеет неверный формат

ForUserContent

Генерирует ключ локализации для пользовательского контента.

public string ForUserContent(string entityType, string entityId, string fieldName)

Параметры:

• entityType — логический тип сущности (например, "post")
• entityId — уникальный стабильный идентификатор (UUID или бизнес-ID)
• fieldName — имя переводимого поля (например, "title")

Возвращает: Строку в формате {microservice}:{entityType}:{entityId}:{fieldName}

Исключения:

• ArgumentException — если любой из параметров имеет неверный формат

ValidateKey (статический)

Проверяет, является ли строка валидным ключом локализации.

public static bool ValidateKey(string key)

Параметры:

• key — ключ для проверки

Возвращает: true, если ключ имеет верный формат, иначе false

Правила форматирования

Формат сегментов ключа

Форматы ключей

Справочник (Reference Data):

{domain}:{concept}:{code}

Пример: hr:profession:software_engineer

Пользовательский контент (User Content):

{microservice}:{entityType}:{entityId}:{fieldName}

Пример: hr:post:550e8400-e29b-41d4-a716-446655440000:title

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

Интеграция в микросервис

// Program.cs
using Platform.I18n.Sdk;

var builder = WebApplication.CreateBuilder(args);

// Инициализация генератора ключей
var keyGenerator = new LocalizationKeyGenerator("hr");
builder.Services.AddSingleton(keyGenerator);

var app = builder.Build();

Генерация ключей при создании справочника

public class ProfessionService
{
    private readonly LocalizationKeyGenerator _keyGenerator;

    public ProfessionService(LocalizationKeyGenerator keyGenerator)
    {
        _keyGenerator = keyGenerator;
    }

    public void CreateProfession(string code, string name)
    {
        // Создание записи в БД
        var profession = new Profession
        {
            Code = code,
            Name = name,
            NameLangId = 2 // ID языка оригинала (например, английский)
        };

        // Генерация ключа для перевода
        var translationKey = _keyGenerator.ForReference(
            domain: "hr",
            concept: "profession",
            code: profession.Code
        );

        // Публикация события для Translation Service
        // messageBus.Publish(new TranslationRequestEvent(translationKey, ...));
    }
}

Генерация ключей для пользовательского контента

public class PostService
{
    private readonly LocalizationKeyGenerator _keyGenerator;

    public PostService(LocalizationKeyGenerator keyGenerator)
    {
        _keyGenerator = keyGenerator;
    }

    public PostDto GetPost(Guid postId, int requestedLanguageId)
    {
        var post = _dbContext.Posts.Find(postId);

        // Если запрошенный язык отличается от языка оригинала
        if (requestedLanguageId != post.TitleLangId)
        {
            var titleKey = _keyGenerator.ForUserContent(
                entityType: "post",
                entityId: postId.ToString(),
                fieldName: "title"
            );

            // Запрос перевода из Translation Service
            // var translatedTitle = await _translationService.GetTranslation(titleKey, requestedLanguageId);
        }

        return new PostDto { /* ... */ };
    }
}

Требования

• .NET Standard 2.0 или выше

Авторы

Steos

Дополнительная документация

Для полного руководства по интеграции с Translation Service см. документацию в репозитории проекта.