$markupProcessing — Настройки обработки разметки

Обработка разметки может быть определена в $projectBuilding.$markupProcessing файла конфигурации (yda.config.yaml по умолчанию):

$projectBuilding:

  $markupProcessing:

    # Задайте настройки обработки разметки здесь в соответствии с данным руководством

• $common — Общие настройки
  • $localization — Общие настройки локализации
    • $stringResourcesFileRelativePath — Относительный путь к файлу строковых ресурсов
    • $localizedStringResourcesConstantName — Имя константы локализованных строковых ресурсов
    • $localeConstantName — Имя константы локали
    • $nameOfConstantForInterpolationToLangHTML_Attribute — Имя константы для заполнения HTML-аттрибута «lang»
    • $locales — Локали
      • outputFileInterimNameExtensionWithoutDot — Промежуточное расширение имени файла без точки
      • localeConstantValue — Значение константы локали
      • keyInLocalizedStringResourcesObject — Ключ в объекте локализованных строковых ресурсов
      • valueOfConstantForInterpolationToLangHTML_Attribute — Значение константы для подстановки в значение аттрибута "lang"
    • $excludedFilesPathsRelativeRelativeToProjectRootDirectory — Относительные корневой директории проекта пути исключённых файлов

$common — Общие настройки

Настройки, общие для всех групп точек входа.

$localization — Общие настройки локализации

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

$stringResourcesFileRelativePath — Относительный путь к файлу строковых ресурсов

Относительный путь к JSON-файлу, в котором хранятся строковые ресурсы. Необходимо указать если локализованные строковые ресурсы хранятся в JSON-файле, но это не единственный способ обеспечения локализованных строковых ресурсов, предлагаемый YDA.

Предполагается, что ключами верхнего уровня JSON-объекта являются строки, соответствующие локалям, такие как russian, ru, en-US и так далее. Особых правил на эти ключи не налагается, но сокращений наподобие ru рекомендуется избегать, так как они могут совпадать с сокращениями другого смысла и запутывать, а если локалей много, то некоторые разработчики вообще могут не понять, что это локаль.

В качестве значений же должны быть указаны дочерние объекты, каждый из которых обязан подчиняться единой структуре:

{
  "$$english": {
    "pages": {
      "products": {
        "list": {
          "metadata": {
            "title": "Products List — ACME Store"
          },
          "topHeading": "Products List"
        },
        "details": {
          "metadata": {
            "title": "Product Details — ACME Store"
          },
          "topHeading": "Product Details"
        }
      }
    }
  },
  "$$russian": {
    "pages": {
      "products": {
        "list": {
          "metadata": {
            "title": "Список продуктов — Магазин «Рога и Копыта»"
          },
          "topHeading": "Список продуктов"
        },
        "details": {
          "metadata": {
            "title": "Описание товара — Магазин «Рога и Копыта»"
          },
          "topHeading": "Описание товара"
        }
      }
    }
  }
}

Структура дочерних объектов в принципе может быть любой, которая валидна с точки зрения формата JSON, в частности может быть сколько угодно уровней вложенности объектов — данные будут инъектированы в Pug в таком виде, в каком они определены и десериализованы с помощью JSON.parse(). Тем не менее, если использовать данный JSON-файл по назначению, то в большинстве случаев там будут только дочерние объекты и строчные свойства как в примере выше.

$localizedStringResourcesConstantName — Имя константы локализованных строковых ресурсов

Имя константы, в которую будут сохранены строковые ресурсы для нужной локали и затем инъектированы в Pug.

Например, пусть файл с путём 01-Source/LocalizedStringResources.json относительно корня проекта имеет следующее JSON-содержимое:

{
  "$$english": {
    "pages": {
      "products": {
        "list": {
          "metadata": {
            "title": "Products List — ACME Store"
          },
          "topHeading": "Products List"
        },
        "details": {
          "metadata": {
            "title": "Product Details — ACME Store"
          },
          "topHeading": "Product Details"
        }
      }
    }
  },
  "$$russian": {
    "pages": {
      "products": {
        "list": {
          "metadata": {
            "title": "Список продуктов — Магазин «Рога и Копыта»"
          },
          "topHeading": "Список продуктов"
        },
        "details": {
          "metadata": {
            "title": "Описание товара — Магазин «Рога и Копыта»"
          },
          "topHeading": "Описание товара"
        }
      }
    }
  }
}

Тогда, при ниже приведённых настройках:

$projectBuilding:

  $markupProcessing:

    $common:

      $localization:

        $stringResourcesFileRelativePath: 01-Source/LocalizedStringResources.json
        $localizedStringResourcesConstantName: $$localizedStringResources

        $locales:

          english:
            $outputFileInterimNameExtensionWithoutDot: english
            $keyInLocalizedStringResourcesObject: $$english

          russian:
            $outputFileInterimNameExtensionWithoutDot: russian
            $keyInLocalizedStringResourcesObject: $$russian

во всех Pug-файлах будет доступна глобальная переменная $$localizedStringResources. Значением её будет один из дочерних объектов из приведённого выше JSON-файла в зависимости от локали страницы:

doctype html


block Requirements

  - const pageStringResources = $$localizedStringResources.pages.products.list;


html(lang=$$LANGUAGE_TAG)

  head

    title= pageStringResources.metadata.title

    meta(charset="utf-8")
    meta(name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no")


  body

    h1= pageStringResources.topHeading

$localeConstantName — Имя константы локали

Хотя строковые ресурсы в Pug-файл инжектируются на нужном языке, может потребоваться программно узнать текущую локаль. Например это потребуется сделать, если нужно вызывать одну Pug-примесей в зависимости от локали:

case $$LOCALE

  when "ENGLISH"

    +Description__English

  when "RUSSIAN"

    +Description__Russian

Для того, чтобы реализовать изложенный принцип, нужно:

1. Указать имя константы, в которое будет сохранено нужное значение локали
2. Указать её значения для каждой локали

Первое как раз и осуществляется через указание $localeConstantName. Второй же пункт следует осуществить, указав возможные значения через ассоциативный массив $locales.

$nameOfConstantForInterpolationToLangHTML_Attribute — Имя константы для заполнения HTML-аттрибута «lang»

Валидная HTML-страница подразумевает указание значения аттрибуту lang у тэга html. Однако поскольку при использовании функциональности локализации в YDA для каждой страницы будет один исходный Pug-файл на все локализации, то вместо статического значения этого аттрибута необходимо указать константу, которую инициализирует YDA в ходе выполнения:

doctype html

html(lang=$$LANGUAGE_TAG)

Имя этой константы (в примере выше это $$LANGUAGE_TAG) указывается через $nameOfConstantForInterpolationToLangHTML_Attribute, а её возможные значения — через ассоциативный массив $locales.

$locales — Локали

Ассоциативный массив с объектными значениями.

• Ключами могут быть любые строки, однако качественное именование должно чётко передавать, что ключи соответствуют локалям, потому сокращения наподобие ru или en не рекомендуются.
• Значениями являются объекты, свойства описаны ниже.

outputFileInterimNameExtensionWithoutDot — Промежуточное расширение имени файла без точки

При использовании функциональности локализации в YDA, для каждой страницы будет один исходный файл вне зависимости от того, сколько локалей. Однако поскольку выходных файлов будет несколько в зависимости от количества локалей, то их имена должны чем-либо отличаться несмотря на наличие общей части. Для этого, YDA добавит выходным файлам промежуточное расширение имени, которое необходимо указать через данное свойство — $outputFileInterimNameExtensionWithoutDot. Например, если имя исходного файла — TopPage.pug, то при указании свойству $outputFileInterimNameExtensionWithoutDot значения russian имя выходного файла будет TopPage.russian.html. Аналогично и для других локалей.

localeConstantValue — Значение константы локали

Соответствующее текущей локали значение константы, имя которой было указано в $localeConstantName.

Например, при приведённых ниже настройках в Pug-код будет инъектирована глобальная константа $$LOCALE, которая может принимать значения "ENGLISH" или "RUSSIAN":

$projectBuilding:

  $markupProcessing:

    $common:

      $localization:

        $localeConstantName: $$LOCALE

        $locales:

          english:

            $outputFileInterimNameExtensionWithoutDot: english
            $localeConstantValue: ENGLISH

          russian:

            $outputFileInterimNameExtensionWithoutDot: russian
            $localeConstantValue: RUSSIAN

keyInLocalizedStringResourcesObject — Ключ в объекте локализованных строковых ресурсов

Ключ верхнего уровня объекта, определённого в JSON-файле, путь которого должен быть указан через $stringResourcesFileRelativePath. Значение, соответствующее этому ключу, будет сохранено в глобальную константу, имя которой должно быть указано через $localizedStringResourcesConstantName.

Допустим по пути StaticPreview/StringResources.json относительно корневой директории проекта находится JSON-файл со следующим содержимым:

{
  "$$english": {
    "pages": {
      "products": {
        "list": {
          "metadata": {
            "title": "Products List — ACME Store"
          },
          "topHeading": "Products List"
        },
        "details": {
          "metadata": {
            "title": "Product Details — ACME Store"
          },
          "topHeading": "Product Details"
        }
      }
    }
  },
  "$$russian": {
    "pages": {
      "products": {
        "list": {
          "metadata": {
            "title": "Список продуктов — Магазин «Рога и Копыта»"
          },
          "topHeading": "Список продуктов"
        },
        "details": {
          "metadata": {
            "title": "Описание товара — Магазин «Рога и Копыта»"
          },
          "topHeading": "Описание товара"
        }
      }
    }
  }
}

Для того, чтобы глобальная константа $$localizedStringResources была проинициализирована верным значением, свойству $keyInLocalizedStringResourcesObject должно быть указано одной из значений, упомянутом в приведённом выше StaticPreview/StringResources.json, то есть $$english или $$russian, каждый в соответствии с нужной локалью:

$projectBuilding:

  $markupProcessing:

    $common:

      $localization:

        $stringResourcesFileRelativePath: 01-Source/LocalizedStringResources.json
        $localizedStringResourcesConstantName: $$localizedStringResources

        $locales:

          english:

            $outputFileInterimNameExtensionWithoutDot: english
            $keyInLocalizedStringResourcesObject: $$english

          russian:

            $outputFileInterimNameExtensionWithoutDot: russian
            $keyInLocalizedStringResourcesObject: $$russian

valueOfConstantForInterpolationToLangHTML_Attribute — Значение константы для подстановки в значение аттрибута "lang"

Соответствующее текущей локали значение глобальной константы, имя которой было указано в $nameOfConstantForInterpolationToLangHTML_Attribute.

Например, при следующих настройках в зависимости от локали будет инъектирована глобальная константа $$HTML_TAG_LANG_ATTRIBUTE_VALUE со значением "en" или "ru" в зависимости от локали.

$projectBuilding:

  $markupProcessing:

    $common:

      $localization:

        $nameOfConstantForInterpolationToLangHTML_Attribute: $$HTML_TAG_LANG_ATTRIBUTE_VALUE

        $locales:

          english:

            $outputFileInterimNameExtensionWithoutDot: english
            $valueOfConstantForInterpolationToLangHTML_Attribute: en

          russian:

            $outputFileInterimNameExtensionWithoutDot: russian
            $valueOfConstantForInterpolationToLangHTML_Attribute: ru

$excludedFilesPathsRelativeRelativeToProjectRootDirectory — Относительные корневой директории проекта пути исключённых файлов

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

$projectBuilding:

  $markupProcessing:

    $common:

      $localization:

        $stringResourcesFileRelativePath: 01-Source/LocalizedStringResources.json
        $localizedStringResourcesConstantName: $$localizedStringResources

        $excludedFilesPathsRelativeRelativeToProjectRootDirectory:

          - Source/Pages/Page1.pug
          - Source/Pages/Page2.pug

        $locales:

          english:
            $outputFileInterimNameExtensionWithoutDot: english
            $keyInLocalizedStringResourcesObject: $$english

          russian:
            $outputFileInterimNameExtensionWithoutDot: russian
            $keyInLocalizedStringResourcesObject: $$russian