255 lines
17 KiB
Markdown
255 lines
17 KiB
Markdown
# translate_util
|
||
|
||
Набор скриптов для перевода визуальной новеллы на движке CatSystem2.
|
||
|
||
Полный путь: игра → распаковка архивов → декомпиляция скриптов → перевод → сборка обратно → компиляция для игры.
|
||
|
||
## Требования
|
||
|
||
- Python 3.9+
|
||
- Windows (нужны `.exe`-утилиты в папке `tool/`)
|
||
- Ключ доступа к любому OpenAI-совместимому API (OpenAI, OpenRouter, локальный сервер и т.д.)
|
||
|
||
### Python-зависимости
|
||
|
||
Всё, кроме одного пакета, — стандартная библиотека Python (`json`, `re`, `csv`, `pathlib`, `subprocess`, `urllib`, `logging` и т.д.), ничего дополнительно ставить не нужно.
|
||
|
||
Единственная внешняя зависимость — официальная реализация формата NSV:
|
||
|
||
```
|
||
pip install nsv
|
||
```
|
||
|
||
Это готовый пакет с [PyPI](https://pypi.org/project/nsv/) (исходники: [nsv-format/nsv-python](https://github.com/nsv-format/nsv-python)), под Windows ставится как готовый wheel — компилятор не нужен. Без него `convert.py`, `names.py` и `translate.py` не запустятся (упадут с `ModuleNotFoundError: No module named 'nsv'`).
|
||
|
||
Наш файл `nsv_io.py` — тонкая обёртка над этим пакетом: сам он не парсит и не экранирует NSV, а только переводит между "строка формата NSV" и "запись перевода с полями line/speaker/pcm/text/translated_text", специфичными для этого проекта. `nsv_io.py` должен лежать рядом с `convert.py`, `names.py`, `translate.py` — они делают `from nsv_io import ...`.
|
||
|
||
Проверить, что Python установлен и виден из консоли:
|
||
|
||
```
|
||
python --version
|
||
```
|
||
|
||
Если команда не найдена — установите Python с [python.org](https://www.python.org/downloads/) (при установке на Windows отметьте галочку "Add python.exe to PATH").
|
||
|
||
### Сторонние утилиты (не Python-пакеты)
|
||
|
||
Эти `.exe` — не часть репозитория, их нужно положить в папку `tool/` самостоятельно (взять из готового тулкита для CatSystem2 или найти по названию):
|
||
|
||
| Файл | Для чего | Используется в |
|
||
|---|---|---|
|
||
| `exkifint_v3.exe` | распаковка `.int`-архивов игры | `extract.py` |
|
||
| `cs2_decompile.exe` | декомпиляция `.cst` → `.txt` | `decompile.py` |
|
||
| `mc.exe` | компиляция `.txt` → `.cst` обратно | `compile.py` |
|
||
|
||
Без них соответствующие шаги пайплайна работать не будут — остальные шаги (Txt to NSV, Names, Перевод, NSV to Txt) от них не зависят и работают на чистом Python.
|
||
|
||
## Структура папок
|
||
|
||
```
|
||
translate_util/
|
||
├── start.py запускать отсюда
|
||
├── extract.py
|
||
├── decompile.py
|
||
├── convert.py
|
||
├── names.py
|
||
├── translate.py
|
||
├── compile.py
|
||
├── nsv_io.py обёртка над пакетом nsv под схему записей проекта
|
||
├── config.json настройки API и перевода
|
||
├── glossary.md глоссарий (имена, термины, заметки по стилю)
|
||
├── prompt.txt системный промпт для LLM
|
||
├── namestable.csv создаётся скриптом names.py
|
||
├── tool/ exkifint_v3.exe, cs2_decompile.exe, mc.exe
|
||
├── txt/ декомпилированные .txt (шаг 2)
|
||
├── json/ .nsv файлы для перевода (шаг 3-5)
|
||
├── txt_translated/ собранные переведённые .txt (шаг 6)
|
||
├── update00/, update01/ оригинальные и переведённые архивы игры
|
||
└── _translate_data/ кэш переводов и логи (создаётся автоматически)
|
||
```
|
||
|
||
## Быстрый старт
|
||
|
||
```
|
||
python start.py
|
||
```
|
||
|
||
Покажет меню на 7 пунктов — можно проходить шаги по порядку, каждый раз возвращаясь в меню.
|
||
|
||
```
|
||
1. Extract — достать файлы из архива игры (.int → .cst/.cstl)
|
||
2. Decompile — .cst → .txt
|
||
3. Txt to NSV — .txt → .nsv (подготовка к переводу)
|
||
4. Names — собрать/применить перевод имён персонажей
|
||
5. Перевод — прогнать текст через LLM
|
||
6. NSV to Txt — .nsv → .txt (сборка перевода обратно)
|
||
7. Compile — .txt → .cst (готово для игры)
|
||
```
|
||
|
||
Каждый скрипт можно запускать и напрямую (`python decompile.py`, `python translate.py` и т.д.) — меню лишь избавляет от необходимости помнить порядок и имена файлов.
|
||
|
||
## Шаг за шагом
|
||
|
||
### 1. Extract — достать файлы из игры
|
||
|
||
```
|
||
python extract.py
|
||
```
|
||
|
||
Спросит путь к папке с игрой и `.exe` игры (для определения версии движка). Извлекает `.cst` (тексты) и `.cstl` (уже локализованные, если есть) файлы из всех архивов (`scene.int`, `fes.int`, `config.int`, `update00.int`...`update19.int`), учитывая, что апдейты перезаписывают базовые файлы. Результат кладётся в папку, которую вы укажете (по умолчанию `extracted_texts/text` и `extracted_texts/localized_text`).
|
||
|
||
### 2. Decompile — .cst → .txt
|
||
|
||
```
|
||
python decompile.py
|
||
```
|
||
|
||
Спросит папку с `.cst` (по умолчанию `update00`). Декомпилирует все файлы через `tool/cs2_decompile.exe` в папку `txt` (кодировка Shift-JIS/CP932).
|
||
|
||
### 3. Txt to NSV — подготовка к переводу
|
||
|
||
```
|
||
python convert.py --txt2nsv
|
||
```
|
||
|
||
Спросит папку с `.txt` (по умолчанию `txt`) и папку для результата (по умолчанию `json`). Разбирает каждый `.txt`, находит строки с текстом (отличает их от игровых команд), и сохраняет в компактном текстовом формате `.nsv` — по одной записи на реплику, с полями: номер строки, спикер, id войсовера (pcm), оригинальный текст, перевод (изначально пустой).
|
||
|
||
`.nsv` — обычный текстовый файл, его можно открыть и посмотреть в любом редакторе. Сам формат — [спецификация NSV](https://github.com/nsv-format/nsv), парсится пакетом `nsv`; маппинг на конкретные поля (line/speaker/pcm/text/translated_text) описан в `nsv_io.py`.
|
||
|
||
### 4. Names — перевод имён персонажей
|
||
|
||
```
|
||
python names.py
|
||
```
|
||
|
||
Меню на 2 пункта:
|
||
|
||
- **1 — собрать имена**: проходит по всем `.nsv` в указанной папке, собирает все уникальные значения поля "спикер" и складывает их в `namestable.csv` (в корне `translate_util`) с пустой колонкой `Translated`.
|
||
- **2 — применить перевод**: читает `namestable.csv`, и для каждой строки, где колонка `Translated` заполнена, заменяет спикера во всех `.nsv` файлах.
|
||
|
||
Откройте `namestable.csv` (Excel, Google Таблицы, любой редактор с поддержкой UTF-8) и заполните колонку `Translated` для нужных имён, затем запустите пункт 2.
|
||
|
||
Пример содержимого:
|
||
|
||
```csv
|
||
Original,Translated
|
||
Michiru,Мичиру
|
||
Sachi,Сачи
|
||
Fan|A,Фанат|А
|
||
```
|
||
|
||
Строки с пустым `Translated` игнорируются — можно переводить имена постепенно.
|
||
|
||
### 5. Перевод текста через LLM
|
||
|
||
Перед первым запуском настройте `config.json`:
|
||
|
||
```json
|
||
{
|
||
"api": {
|
||
"base_url": "https://api.openai.com/v1",
|
||
"api_key": "sk-ваш-ключ",
|
||
"model": "gpt-4o",
|
||
"temperature": 0.3,
|
||
"max_tokens": 4092,
|
||
"timeout_seconds": 120
|
||
},
|
||
"translation": {
|
||
"source_language": "English",
|
||
"target_language": "Russian",
|
||
"batch_size": 10,
|
||
"context_before": 2,
|
||
"context_after": 2,
|
||
"max_retries": 3,
|
||
"retry_delay_seconds": 5
|
||
},
|
||
"paths": {
|
||
"json_dir": "json",
|
||
"glossary_file": "glossary.md"
|
||
}
|
||
}
|
||
```
|
||
|
||
| Параметр | Что значит |
|
||
|---|---|
|
||
| `base_url` | адрес API — для OpenAI, OpenRouter или локального сервера (LM Studio, Ollama и т.д.) |
|
||
| `api_key` | ваш ключ |
|
||
| `model` | название модели у выбранного провайдера |
|
||
| `temperature` | ниже — переводит более предсказуемо и буквально, выше — вольнее |
|
||
| `max_tokens` | лимит длины ответа на один запрос |
|
||
| `reasoning_effort` | необязательное поле, если модель поддерживает режимы рассуждения (например `"low"`/`"medium"`/`"high"`) |
|
||
| `batch_size` | сколько реплик отправляется в LLM за один запрос |
|
||
| `context_before` / `context_after` | сколько соседних реплик показывать модели для контекста (до — уже переведённые, после — оригинал) |
|
||
| `max_retries` / `retry_delay_seconds` | сколько раз и с какой паузой повторять запрос при сбое |
|
||
|
||
Отредактируйте `glossary.md` — впишите имена персонажей, термины и заметки по стилю перевода. Формат:
|
||
|
||
```markdown
|
||
## Characters
|
||
- Michiru: Мичиру
|
||
|
||
## Terms
|
||
- Idol: Айдол
|
||
|
||
## Notes
|
||
- Michiru обращается к другим неформально.
|
||
```
|
||
|
||
Запуск:
|
||
|
||
```
|
||
python translate.py
|
||
```
|
||
|
||
Спросит, какие `.nsv` файлы переводить — имена файлов через запятую (без расширения) или `all` для всех. Дальше работает автоматически:
|
||
|
||
- бьёт текст на пачки и отправляет в LLM вместе с глоссарием и контекстом соседних реплик;
|
||
- пишет перевод сразу в файл после каждой пачки — можно прервать (Ctrl+C) и продолжить позже, ничего не потеряется;
|
||
- строки, у которых перевод уже есть, пропускаются — safe перезапускать сколько угодно раз;
|
||
- при сбое или странном ответе модели — повторяет запрос; если не получилось после всех попыток — идёт дальше, а в конце выводит список проблемных мест для повторного прогона;
|
||
- одинаковый исходный текст переводится один раз и берётся из кэша при повторных встречах (файл `_translate_data/translation_cache.json`) — экономит и деньги, и время.
|
||
|
||
Логи каждого запуска — в `_translate_data/translate_logs/`, сырые запросы/ответы API — в `_translate_data/raw_api_logs/` (полезно для отладки, если модель ведёт себя странно).
|
||
|
||
Если после прогона остались проблемные пачки — просто запустите `python translate.py` ещё раз для тех же файлов, уже переведённое не тронется.
|
||
|
||
### 6. NSV to Txt — сборка перевода обратно
|
||
|
||
```
|
||
python convert.py --nsv2txt
|
||
```
|
||
|
||
Спросит:
|
||
- папку с оригинальными `.txt` (по умолчанию `txt`) — используется как "скелет", все игровые команды и структура берутся отсюда;
|
||
- папку с переведёнными `.nsv` (по умолчанию `json`);
|
||
- папку для результата (по умолчанию `txt_translated`);
|
||
- какое поле использовать — `text` (оригинал, для проверки, что ничего не сломалось) или `translated_text` (реальный перевод, стандартный выбор).
|
||
|
||
Соберёт `.txt`-файлы, готовые к компиляции, подставив перевод только в текстовые строки и не тронув остальное.
|
||
|
||
### 7. Compile — .txt → .cst
|
||
|
||
```
|
||
python compile.py
|
||
```
|
||
|
||
Спросит папку с переведёнными `.txt` (по умолчанию `txt_translated`) и папку для результата (по умолчанию `update01`). Компилирует всё через `tool/mc.exe`.
|
||
|
||
После этого `update01` можно класть обратно в игру (или собирать в архив — зависит от того, как игра подхватывает патчи).
|
||
|
||
## Формат .nsv
|
||
|
||
Простой текстовый формат ([спецификация](https://github.com/nsv-format/nsv), реализация — пакет `nsv`): одна запись — 5 строк подряд (номер, спикер, pcm, оригинал, перевод), затем пустая строка-разделитель. Пустое значение поля — одиночный `\`. Внутри текста `\` экранируется как `\\`, настоящий перенос строки — как `\n`.
|
||
|
||
Файл можно открыть в любом текстовом редакторе. LLM никогда не видит это экранирование напрямую — при отправке в модель текст уже "распакован" в обычный читаемый вид, а при сохранении на диск запаковывается заново автоматически.
|
||
|
||
## Частые проблемы
|
||
|
||
**`translate.py` падает с ошибкой про кодировку/JSON при чтении файла** — убедитесь, что используете `.nsv` файлы, созданные текущей версией `convert.py --txt2nsv`, а не старые `.json` от прежних версий скриптов.
|
||
|
||
**В игре после компиляции вместо буквы стоит `?`** — где-то в переводе оказался символ, не входящий в Shift-JIS/CP932 (например длинное тире `—`, `™`, эмодзи). `convert.py` при сборке (`--nsv2txt`) старается автоматически заменить самые частые проблемные символы, но если что-то новое проскочило — `compile.py`/`convert.py` покажут ошибку кодировки в консоли, укажут на файл, надо будет поправить перевод вручную в `.nsv`.
|
||
|
||
**Перевод потерял `[слова] [в] [скобках]` или `\`-теги** — это значит модель их не сохранила, несмотря на инструкцию в `prompt.txt`. Найдите строку в `.nsv`, поправьте вручную или сотрите `translated_text` у этой записи и запустите `translate.py` заново — тогда LLM переведёт её ещё раз.
|
||
|
||
**Хочу начать перевод заново с нуля** — очистите поле `translated_text` в нужных `.nsv` файлах (или пересоздайте их через `convert.py --txt2nsv`), и при желании удалите `_translate_data/translation_cache.json`, чтобы не подтягивался старый перевод из кэша.
|