ss14-localization-strings

name: ss14-localization-strings description: Руководство по работе с файлами локализации (.ftl) и строками в Space Station 14. Используй этот навык при добавлении или изменении игровых текстов, описаний предметов и интерфейса.

SS14 Localization Strings (Russian)

Этот скилл описывает правила и стандарты работы со строками локализации в Space Station 14 (Fluent Translation Lists - FTL).

Граница ответственности

Этот skill покрывает формат FTL, структуру строк и практику локализации. Строгие naming-нормативы (формат ent-*, kebab-case, длина name/desc, английские fallback-поля в прототипах) централизованы в ss14-naming-conventions. Если здесь встречается naming-фрагмент, который расходится с ss14-naming-conventions, применяй ss14-naming-conventions.

1. Структура файлов и пути

Файлы .ftl располагаются в Resources/Locale/{CultureCode}/.... Для русского языка это Resources/Locale/ru-RU/.

Типы файлов

• Прототипы (Entity Prototypes):
  • Лежат в папках, соответствующих структуре прототипов, часто с префиксом _prototypes.
  • Пример: Resources/Locale/ru-RU/_prototypes/entities/objects/weapons/guns.ftl
• Интерфейс и сообщения:
  • Лежат в тематических папках (например, interaction, ui, chat).
  • Пример: Resources/Locale/ru-RU/ui/main-menu.ftl

2. Формат строк и FTL синтаксис

Стандартные строки (Ключ-Значение)

# Простой ключ
my-system-message-hello = Привет, космос!

# Многострочное значение (отступ обязателен, используйте ПРОБЕЛЫ, а не табы)
my-system-popup-error =
    Ошибка доступа!
    Пожалуйста, обратитесь к администратору.

Строки для прототипов (Entities)

Для сущностей (EntityPrototype) движок автоматически ищет строки по ID сущности с префиксом ent-. Используйте атрибуты Fluent (начинаются с точки) для описаний и суффиксов.

• Название (Name): ent-{PrototypeID} = название
• Описание (Description): Аттрибут .desc
• Суффикс (Editor Suffix): Аттрибут .suffix

Пример: Если есть прототип с id: Crowbar

ent-Crowbar = лом
    .desc = Инструмент для рычагового воздействия.
    .suffix = Инструмент

🚫 Анти-паттерн: НЕ английский язык в YAML прототипе

Поля name, description, suffix в YAML прототипе являются fallback значениями. Они должны быть прописаны на АНГЛИЙСКОМ языке и соответствовать английской локализации.

🚫 Анти-паттерн: Различие названий в YAML и FTL

Поля в прототипе обязаны соответствовать английской локализации в FTL. Изменение одного требует изменения другого.

🚫 Анти-паттерн: Отсутствие экранирования тегов в начале строки

Если строка в FTL начинается с тега, например [bold] Строка [/bold], первый тег должен быть экранирован. Парсер считает [ в начале строки как сломанную структуру условных конструкций. Если нужно начать строку с тега требуется экранировать его с помощью ZERO WHITESPACE.

Пример, когда экранирование требуется

ent-MyItem = предмет
    .desc =
    [bold] мое длинное описание[/bold]

Пример, когда экранирование НЕ требуется

ent-MyItem = предмет
    .desc = [bold] мое длинное описание[/bold]

3. Наследование локализации

FTL не поддерживает автоматическое наследование строк от родительского прототипа в том виде, как это делает YAML. Если вы создаете новый прототип CrowbarRed с parent: Crowbar, вы обязаны создать для него свои строки локализации, иначе он будет называться ent-CrowbarRed.

Однако, можно ссылаться на другие строки внутри FTL, используя перекрестные ссылки на атрибуты:

ent-CrowbarRed = красный лом
    .desc = { ent-Crowbar.desc }

4. Встроенные функции и условия

SS14 поддерживает специальные функции FTL для склонения и грамматики.

🧬 Основные функции (Functions)

• THE($ent): Добавляет определенный артикль (English only).
• SUBJECT($ent): Возвращает местоимение субъекта (он/она/оно) в зависимости от пола сущности.
• OBJECT($ent): Возвращает местоимение объекта (его/её/оно).
• GENDER($ent): Возвращает пол сущности (male, female, epicene, neuter) для селекторов.
• CAPITALIZE($text): Делает первую букву заглавной.

🔀 Селекторы (Selectors)

Используются для изменения текста в зависимости от пола или числа.

Пример (Гендерность):

examine-verb-details = { GENDER($user) ->
    [male] Он рассматривает
    [female] Она рассматривает
    *[other] Оно рассматривает
} { THE($target) }.

Пример (Переменные):

# $count - переменная, переданная из кода
reagent-container-name = { $count ->
    [one] Пробирка
    *[other] Пробирки
}

Экранирование

Если текст начинается с тега форматирования (например [bold]), экранируйте открывающую скобку: {"["}bold]Text.

5. Нейминг и Стиль (Naming & Style Guide)

Следуйте этим правилам неукоснительно. Они задают единый визуальный стиль игры.

📝 Правила именования (Naming)

1. Названия предметов (Names) — с маленькой буквы.

   • Исключение: Имена собственные или начало предложения (но в инвентаре предметы пишутся с маленькой).
   • ✅ ent-Crowbar = лом
   • ✅ ent-AccessCard = ID карта
   • ❌ ent-Crowbar = Лом

2. Описания (Descriptions) — с большой буквы.

   • Это полноценные предложения.
   • ✅ .desc = Полезный инструмент.
   • ❌ .desc = полезный инструмент

🎨 Стиль описаний (Visual Style)

1. Только визуальная информация (Visuals only).

   • Описание должно говорить о том, что персонаж видит или чувствует.
   • Избегайте сухих технических данных, если они не видны на предмете (например, "Наносит 10 урона").

2. OOC допустим только как явный OOC-блок.

   • OOC-фразы должны начинаться с префикса OOC:.
   • Без маркера OOC: добавлять внешне-игровые инструкции запрещено.
   • ❌ "Нажмите кнопку G чтобы активировать."
   • ✅ "OOC: Нажмите кнопку G чтобы активировать."
   • ✅ "Выглядит тяжелым и надежным."

🚫 Анти-паттерны в FTL

1. Хардкод путей: Не пишите пути к спрайтам или звукам в локализации.
2. Дублирование ключей: Если ключ повторяется в разных файлах, поведение может быть непредсказуемым.
3. Отсутствие аргументов: Если строка требует аргумент {$user}, а вы его не передали в коде — будет ошибка.
4. Tab Indentation: Используйте пробелы для отступов, табы ломают парсер Fluent.

Примеры

Хорошо:

ent-StandardRadio = радиостанция
    .desc = Портативное устройство связи.

interaction-popup-blocked = { THE($user) } пытается открыть дверь, но она заперта!

Плохо:

ent-StandardRadio = Радиостанция  # С большой буквы
    .desc = используется для общения (нажмите T). # OOC инфо, с маленькой буквы

interaction-popup-blocked = Дверь закрыта. # Нет контекста кто пытается открыть

6. Теги форматирования текста (Rich Text)

Список доступных тегов форматирования.