Update documentation and code snippets

docs/locales/en/LC_MESSAGES/root/flags.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Argenta \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-11-03 19:01+0300\n"
+"POT-Creation-Date: 2025-12-02 22:27+0300\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language: en\n"
@@ -25,36 +25,140 @@ msgstr ""
 
 #: ../../root/flags.rst:6
 msgid ""
-"Флаги (или параметры) — это специальные аргументы, которые пользователь "
-"может добавлять к командам для управления их поведением."
+"Флаги — это специальные параметры, которые пользователь может добавлять к"
+" командам для управления их поведением."
 msgstr ""
 
-#: ../../root/flags.rst:11
-msgid "Синтаксис флагов"
+#: ../../root/flags.rst:9
+msgid "Зачем нужны флаги в командах"
 msgstr ""
 
-#: ../../root/flags.rst:13
-msgid "Общий синтаксис выглядит так:"
+#: ../../root/flags.rst:12
+msgid "Управление поведением команды"
+msgstr ""
+
+#: ../../root/flags.rst:14
+msgid ""
+"Основная цель флагов — предоставить способ изменить логику работы команды"
+" без её переработки. Команда может работать в нескольких режимах: "
+"стандартном, подробном, отладочном или упрощённом. Флаги переключают эти "
+"режимы по требованию пользователя, оставляя основную функциональность "
+"неизменной."
+msgstr ""
+
+#: ../../root/flags.rst:17
+msgid "Опциональность и удобство"
 msgstr ""
 
 #: ../../root/flags.rst:19
 msgid ""
+"Флаги решают проблему обязательности параметров. Если все параметры "
+"команды сделать обязательными, это затруднит использование команды. Флаги"
+" же позволяют задать значения только необходимые в конкретной ситуации, "
+"остальные используют значения по умолчанию."
+msgstr ""
+
+#: ../../root/flags.rst:22
+msgid "Когда могут понадобиться флаги"
+msgstr ""
+
+#: ../../root/flags.rst:24
+msgid "**Переключение режимов работы**"
+msgstr ""
+
+#: ../../root/flags.rst:25
+msgid ""
+"Команда выполняет развёртывание приложения обычно, но нужен режим без "
+"фактического развёртывания (dry-run) для проверки. Флаг ``--dry-run`` "
+"переключит режим работы."
+msgstr ""
+
+#: ../../root/flags.rst:27
+msgid "**Настройка уровня детальности**"
+msgstr ""
+
+#: ../../root/flags.rst:28
+msgid ""
+"При отладке или анализе требуется больше информации о процессе выполнения"
+" команды. Флаги ``--verbose`` или ``--debug`` предоставляют подробный "
+"вывод."
+msgstr ""
+
+#: ../../root/flags.rst:30
+msgid "**Управление поведением при ошибках**"
+msgstr ""
+
+#: ../../root/flags.rst:31
+msgid ""
+"По умолчанию команда может прерваться при первой ошибке. Флаг ``--force``"
+" позволит продолжить работу, пропуская некритичные ошибки."
+msgstr ""
+
+#: ../../root/flags.rst:33
+msgid "**Форматирование вывода**"
+msgstr ""
+
+#: ../../root/flags.rst:34
+msgid ""
+"Команда выводит данные текстом, но в некоторых сценариях нужен JSON или "
+"CSV. Флаг ``--format=json`` переключит формат вывода."
+msgstr ""
+
+#: ../../root/flags.rst:36
+msgid "**Комбинирование опций**"
+msgstr ""
+
+#: ../../root/flags.rst:37
+msgid ""
+"Часто нужна комбинация нескольких изменений: подробный вывод, dry-run "
+"режим и JSON формат. Несколько флагов решают эту задачу одновременно."
+msgstr ""
+
+#: ../../root/flags.rst:40
+msgid "Практическое значение"
+msgstr ""
+
+#: ../../root/flags.rst:42
+msgid ""
+"Флаги делают команды более предсказуемыми и контролируемыми. Пользователь"
+" может начать с простого использования, а затем добавлять флаги по мере "
+"необходимости. Это особенно важно при автоматизации задач в скриптах, где"
+" гибкость интерфейса критична."
+msgstr ""
+
+#: ../../root/flags.rst:44
+msgid ""
+"Флаги также облегчают интеграцию команд в различные системы, так как "
+"дополнительное поведение достигается без изменения структуры команды, а "
+"только через передачу опциональных параметров."
+msgstr ""
+
+#: ../../root/flags.rst:49
+msgid "Синтаксис флагов"
+msgstr ""
+
+#: ../../root/flags.rst:51
+msgid "Общий синтаксис выглядит так:"
+msgstr ""
+
+#: ../../root/flags.rst:57
+msgid ""
 "Флаг состоит из префикса (``-``, ``--`` или ``---``), имени и, "
 "опционально, значения, которое указывается через пробел."
 msgstr ""
 
-#: ../../root/flags.rst:24
+#: ../../root/flags.rst:62
 msgid "Два типа флагов"
 msgstr ""
 
-#: ../../root/flags.rst:26
+#: ../../root/flags.rst:64
 msgid ""
 "Флаги бывают двух основных видов: без значений (переключатели) и со "
 "значениями. ``Argenta`` позволяет регистрировать и вводить флаги обоих "
 "типов в любой последовательности для одной команды."
 msgstr ""
 
-#: ../../root/flags.rst:29
+#: ../../root/flags.rst:67
 msgid ""
 "Ошибки валидации не выбрасывают исключений. Вместо этого у каждого "
 "объекта :ref:`InputFlag <root_api_command_input_flag>` есть атрибут "
@@ -63,114 +167,145 @@ msgid ""
 " <root_api_command_flag>`."
 msgstr ""
 
-#: ../../root/flags.rst:31
+#: ../../root/flags.rst:69
 msgid ""
 "При регистрации флага можно задать правила валидации для его значения. По"
 " умолчанию любое значение считается корректным. Валидацию можно настроить"
 " несколькими способами:"
 msgstr ""
 
-#: ../../root/flags.rst:36
-msgid "Ограничение по списку возможных значений"
+#: ../../root/flags.rst:74
+msgid "Флаги против аргументов"
 msgstr ""
 
-#: ../../root/flags.rst:38
-msgid "Вы можете заранее определить список допустимых значений для флага."
-msgstr ""
-
-#: ../../root/flags.rst:40
+#: ../../root/flags.rst:76
 msgid ""
-"Предположим, у вас есть флаг ``--format``, который может принимать только"
-" значения ``json`` или ``xml``."
+"В контексте Argenta флаги и аргументы относятся к разным уровням "
+"взаимодействия с приложением и имеют принципиально разные сферы действия."
 msgstr ""
 
-#: ../../root/flags.rst:54
-msgid "Проверка с помощью регулярных выражений"
+#: ../../root/flags.rst:79
+msgid "Определение и назначение"
 msgstr ""
 
-#: ../../root/flags.rst:56
+#: ../../root/flags.rst:81
 msgid ""
-"Для более сложных проверок можно использовать регулярные выражения. Это "
-"полезно, когда значение должно соответствовать определённому формату "
-"(например, email-адрес, дата или номер телефона)."
+"**Аргументы** — это параметры, передаваемые при запуске приложения один "
+"раз при инициализации. Они определяют глобальное состояние и конфигурацию"
+" приложения на протяжении всей его работы, например адрес базы данных, "
+"уровень логирования или режим работы."
 msgstr ""
 
-#: ../../root/flags.rst:58
+#: ../../root/flags.rst:83
 msgid ""
-"Допустим, флаг ``--email`` должен принимать только корректные "
-"email-адреса."
+"API и более подробное описание в разделах :ref:`ArgParser "
+"<root_api_orchestrator_argparser>` и :ref:`Arguments "
+"<root_api_orchestrator_arguments>`."
 msgstr ""
 
-#: ../../root/flags.rst:69
+#: ../../root/flags.rst:85
 msgid ""
-"Встроенная валидация избавляет от необходимости писать проверки вручную и"
-" делает код более декларативным."
+"**Флаги** — это параметры командных операций, доступные в рамках "
+"интерактивной сессии при вводе каждой новой команды. Они позволяют "
+"модифицировать поведение конкретной команды без перезагрузки приложения."
 msgstr ""
 
-#~ msgid "Флаги"
-#~ msgstr ""
+#: ../../root/flags.rst:87
+msgid ""
+"API и более подробное описание в разделе :ref:`Flag "
+"<root_api_command_flag>`."
+msgstr ""
 
-#~ msgid ""
-#~ "Флаги (или параметры) — это специальные"
-#~ " аргументы, которые конечный юзер может "
-#~ "добавлять к командам, чтобы управлять их"
-#~ " поведением."
-#~ msgstr ""
+#: ../../root/flags.rst:92
+msgid "Ключевые различия"
+msgstr ""
 
-#~ msgid "Обобщённый синтаксис выглядит так:"
-#~ msgstr ""
+#: ../../root/flags.rst:94
+msgid "**Время жизни и область действия**"
+msgstr ""
 
-#~ msgid ""
-#~ "То есть, у флага обязательно должен "
-#~ "быть префикс, который может быть одним,"
-#~ " двум или трем минусам. После "
-#~ "префикса следует имя флага, без пробела,"
-#~ " после, через пробел, идёт значение "
-#~ "флага, если оно есть."
-#~ msgstr ""
+#: ../../root/flags.rst:95
+msgid ""
+"Аргументы передаются один раз при запуске приложения и сохраняют действие"
+" на весь период работы (скоуп **APP**). Флаги наоборот локальны и живут в"
+" рамках скоупа **REQUEST**."
+msgstr ""
 
-#~ msgid ""
-#~ "Флаги бывают двух основных видов: без"
-#~ " значений (переключатели) и со значениями."
-#~ " ``Argenta`` позволяет регистрировать и "
-#~ "вводить флаги обоих типов в любой "
-#~ "последовательности  для одной команды."
-#~ msgstr ""
+#: ../../root/flags.rst:97
+msgid "**Частота изменения**"
+msgstr ""
 
-#~ msgid ""
-#~ "Ошибки валидации значений являются пассивными,"
-#~ " их не нужно обрабатывать явно. У "
-#~ "каждого инстанса :ref:`InputFlag "
-#~ "<root_api_command_input_flag>` есть поле ``status``,"
-#~ " по которому можно определить результат "
-#~ "валидации флага. **Конкретная реализация и "
-#~ "описание API вы можете найти в "
-#~ "разделе** :ref:`Flag <root_api_command_flag>`."
-#~ msgstr ""
+#: ../../root/flags.rst:98
+msgid ""
+"Для изменения аргументов необходимо перезапустить приложение. Флаги можно"
+" менять между каждым вводом команды без остановки приложения."
+msgstr ""
 
-#~ msgid ""
-#~ "При регистрации флага вы можете указать"
-#~ " допустимые для него значения, по "
-#~ "умолчанию любое введённое значение для "
-#~ "флага будет валидным. Допустимые значения "
-#~ "можно указать различными способами:"
-#~ msgstr ""
+#: ../../root/flags.rst:100
+msgid "**Уровень конфигурации**"
+msgstr ""
 
-#~ msgid "**Пример:**"
-#~ msgstr ""
+#: ../../root/flags.rst:101
+msgid ""
+"Аргументы управляют глобальной конфигурацией приложения и его окружением."
+" Флаги управляют поведением отдельных команд и операций пользователя."
+msgstr ""
 
-#~ msgid ""
-#~ "Для более сложных проверок вы можете "
-#~ "использовать регулярные выражения. Это "
-#~ "особенно полезно, когда значение должно "
-#~ "соответствовать определённому формату, например, "
-#~ "быть email-адресом, датой или номером "
-#~ "телефона."
-#~ msgstr ""
+#: ../../root/flags.rst:103
+msgid "**Использование**"
+msgstr ""
 
-#~ msgid ""
-#~ "Встроенная валидация избавляет вас от "
-#~ "необходимости писать ручные проверки и "
-#~ "делает ваш код более декларативным."
-#~ msgstr ""
+#: ../../root/flags.rst:104
+msgid ""
+"Аргументы задают начальное состояние системы: что подключить, как "
+"работать. Флаги управляют тактикой выполнения команд: как её выполнить, с"
+" какими изменениями."
+msgstr ""
+
+#: ../../root/flags.rst:109
+msgid "Практические примеры в Argenta"
+msgstr ""
+
+#: ../../root/flags.rst:111
+msgid "При запуске приложения Argenta передаются аргументы:"
+msgstr ""
+
+#: ../../root/flags.rst:113
+msgid "Адрес подключения к базе данных"
+msgstr ""
+
+#: ../../root/flags.rst:114
+msgid "Режим работы (production, development, testing)"
+msgstr ""
+
+#: ../../root/flags.rst:115
+msgid "Уровень логирования"
+msgstr ""
+
+#: ../../root/flags.rst:116
+msgid "Путь к конфигурационным файлам"
+msgstr ""
+
+#: ../../root/flags.rst:118
+msgid "В интерактивной сессии для каждой команды указываются флаги:"
+msgstr ""
+
+#: ../../root/flags.rst:120
+msgid "``deploy --verbose --dry-run`` — для текущей команды развёртывания"
+msgstr ""
+
+#: ../../root/flags.rst:121
+msgid "``backup --compress --encrypted`` — для команды резервного копирования"
+msgstr ""
+
+#: ../../root/flags.rst:122
+msgid "``test --parallel --coverage`` — для команды тестирования"
+msgstr ""
+
+#: ../../root/flags.rst:124
+msgid ""
+"Один пользователь может выполнить разные команды с разными флагами в "
+"одной сессии приложения, без необходимости перезапуска с новыми "
+"аргументами."
+msgstr ""