Пайплайн локалізації

Мова: English · Українська

Відкривається Tools → Localization Pipeline…. Заголовок вікна: Localization Pipeline.

Діалог навмисно тонкий (ui/pipeline_wizard_dialog.py): власного пайплайну він не рахує. Кожна кнопка запускає той самий QAction, що й меню Tools. Кроки, які є цілими воркфлоу, вбудовуються в праву панель замість другого вікна.

Ліворуч: дерево кроків з іконкою статусу і лічильником. Праворуч: інструмент або пояснення плюс кнопка запуску. Внизу: Refresh і Close. Повернення у вікно перечитує проєкт через 250 мс.

Заголовок: Localization pipeline — N / M steps complete.

Які кроки видно

steps_for(plugin.get_capabilities()). Порожня множина capabilities валідна: лишаються всі кроки, що працюють на витягнутому тексті. Крок з requires="…" з’являється лише якщо активний плагін оголосив це ім’я.

Визнані імена capabilities (з plugins/base_game_rules.py):

Twilight Princess (plugins/zelda_bmg) оголошує всі чотири. Default Plugin Template — жодної.

Кроки (як у коді)

Порядок у STEPS:

1. Mark up the script (markup)

Вбудовано: Script Markup Studio (Close сховано; Close хоста — у майстра).

Вокзру — проза. Розмітка каже, який рядок — спікер, який — репліка. Merge Speakers і Context Builder читають цей файл.

Статус: покриті approved-мітками ненульові рядки джерела, без типу Unmarked. «No script found for this game» і «script not marked up» — різні відповіді.

Робити: закінчити розмітку перед Merge Speakers. Не пропускати її в надії, що ALL-CAPS вгадає склад.

Деталі: 9. Script Markup.

2. Name the speakers (speakers) — дитина markup

Видно лише якщо в capabilities є speaker_attribution.

Кнопка: Merge speakers from the script → merge_speakers_action.

Гра групує рядки за голосом (Voice 8, імена placement). Скрипт має показувані імена. Крок з’єднує їх по тексту рядка (SpeakerMergeHandler.merge_from_script). Потрібен відкритий проєкт і get_speaker_for_string. Якщо рядків спікера в розмітці немає, може вгадувати з ALL-CAPS і попередити. Apply зберігає аліаси біля проєкту. Імена далі потрапляють у поле Speaker, віртуальні теки, промпти перекладу і сіди глосарія.

Статус: названі placeholder-коди / усі placeholder-коди, які плагін ще звітує.

Робити merge перед автопроходом глосарія, якщо персонажів треба сіяти під вирішеним ім’ям, а не CLERK_B. Не голосувати рядок скрипта на спікера плагіна System (TP: таблички, титри, вікна предметів, назви локацій, howling stones, картки босів).

3. Build the story context (context)

Вбудовано: MemePalace Context Builder (власні Close / Done сховані; Stop лишається, поки йде задача).

Копіює розмітку в MemePalace і прив’язує кожен ігровий рядок до місця в сюжеті.

Заголовок вікна MemPalace Context Builder. Вкладка 1. Source: Select project…, Import/Sync, Continue to Story Context →. Далі:

• Step 1 — Find Context Automatically — без AI.
• Step 2 — Build Timeline with AI
• Step 3 — Analyze Character Voices with AI

Кроки 2–3 потребують AI-провайдера. Вони не вигадують терміни глосарія і не замінюють Merge Speakers.

Статус: усе або нічого — “story context built”, якщо є шлях БД MemePalace, інакше “no story context yet”.

Без цього кроку переклад усе одно працює як «переклади це речення». З ним промпт може знати сцену.

Робити крок 1 перед timeline/voices. Не чекати голосів, поки рядки не зв’язані.

4. Prepare and enrich the glossary (glossary)

Вбудовано: Prepare Glossary (GlossaryPipelineHandler з target_step="auto").

Один автоматичний прохід:

1. Посіяти терміни з даних гри (get_glossary_seed_entries) і персонажів Script Markup.
2. Перейменувати сіди аліасами Merge Speakers (один голос на кількох персонажів стає кількома термінами, ніколи "A / B").
3. Просканувати вибрані блоки проєкту на пропущені терміни.
4. Зібрати описи з доступного контексту.
5. Запропонувати варіанти перекладу.

Прохід не зупиняється на питаннях. Неоднозначності лишаються як AI-нотатки / черга review.

UI (режим auto):

• Project blocks: Whole project плюс список із галочками. Радіо Area сховані.
• Also propose translations now увімкнено і сховано.
• Опційно: Re-scan every selected block with AI (зазвичай лише нові/змінені блоки).
• Опційно: Resume unfinished entries only, коли частині термінів ще потрібен опис або переклад.
• Опційно: Force re-translate already translated terms для примусового переперекладу всіх наявних записів глосарію за актуальними правилами.
• Опційно: Reconcile related terms afterwards — після перекладу порівняти споріднені записи й узгодити їх (див. нижче).
• Кнопка: Запустити автоматичний прохід глосарія....

Статус: порожньо → “automatic pass not run”; інакше N terms; M awaiting review (непідтверджені). Partial, поки черга review не порожня.

Ручний глосарій: Глосарій… / Ctrl+G. Те саме сховище. Має пряму кнопку «Force Retranslate...» (з автоматичним створенням бекапу glossary.json.bak) для примусового переперекладу всіх термінів за допомогою ШІ та оновлення варіантів на льоту. Коли завантажено референсний патч, сторонні референсні варіанти виділяються кольором (блакитний/курсив), захищені від випадкового застосування подвійним кліком та ізольовані в нотатках ШІ (з автоматичним контекстом з першого входження, якщо прямого варіанта немає).

Робити спочатку налаштувати AI (11, 5). Не вважати непідтверджені записи блокером для перекладу тексту.

Інші заголовки запуску в GlossaryBuildDialog для не-auto шляхів (Sweep Text with AI, Describe Glossary Terms, Build Glossary from Text) з глибинами:

Розмір чанка: Local / small (2000), Balanced (4000), Cloud / large (8000).

Як глосарій лишається узгодженим

• Один термін — один запис. Термін, знайдений побудовою, зіставляється з наявними записами за точним написанням, потім за регістром і пробілами, потім за аліасом, потім за канонічним ключем, який згортає множину, артиклі та присвійні форми. Rupees із пізнішого чанка потрапляє в Rupee, а не стає другим записом. Термін, доданий вручну, додається як написано. Записи, які вже мають спільний канонічний ключ, перелічуються в лозі під час завантаження і ніколи не зливаються автоматично.
• Той самий вхід — той самий глосарій. Результати застосовуються у фіксованому порядку, хоч би в якому порядку відповідали запити; термін отримує найчастіше написання з тексту.
• Запити знають, що вже вирішено. Кожен чанк sweep і кожен переклад терміна бачить уже вирішені записи зі спільним словом (до 40, рішення людини першими). Спершу перекладаються терміни з одного слова, потім із двох, потім довші, а споріднені — один за одним, тож Clawshots перекладається зі знанням того, що отримав Clawshot, а Zora Armor — зі знанням Zora.
• Узгодження (опційно). Після перекладу записи, які є тим самим терміном в іншому написанні або мають спільне слово, порівнюються — один запит на групу, що виглядає неузгодженою. Написання одного терміна зливаються (інше написання лишається аліасом, його переклад — варіантом); переклади вирівнюються до спільного кореня. Підтверджені записи не змінюються. Кожна зміна є у звіті та в лозі, а повторний запуск нічого не змінює.
• Що потрапляє в промпт перекладу. Рядки глосарію для термінів із тексту, включно з множиною (Rupees знаходить Rupee). Термін, знайдений лише всередині довшого терміна, окремо не подається (Lake Hylia, без окремого Hylia). Записи без перекладу пропускаються. Щонайбільше 40 рядків: спершу підтверджені та написані вручну, потім машинні; нотатки в промпті обрізаються до 300 символів (у редакторі лишається повна нотатка).
• Зберігання. Прохід побудови записує файл глосарію кожні 20 результатів і наприкінці, замінюючи файл одним кроком. Кожен запис має сталий id. Видалений або злитий запис лишає у файлі позначку deleted_at, щоб синхронізація з Companion не повернула його; перейменований запис зіставляється за id. Повторний sweep додає свідчення до перекладеного запису, а не скидає його.

Глосарії серії (спільні для ігор однієї серії)

Глосарії, спільні для кількох проєктів: гра (її проєкти GC і HD), покоління, ціла серія. Кожен — файл у форматі glossary.json (core/glossary/series.py). Проєкт має ланцюг таких файлів, від найближчого; глосарій проєкту має перевагу, далі ближчий рівень над дальшим.

• Глосарії в теках (без налаштування): проєкт у <Серія>\<Гра>\…\picoripi\ використовує кожен _glossary\glossary.json, знайдений у теках над ним: спершу <Гра>\_glossary\, потім <Серія>\_glossary\. Покладіть файл туди, і кожен проєкт гри чи серії його має. "series_glossary_auto": false у метаданих .uiproj (пункт меню Use the _glossary folders above the project) вимикає це.
• Явні зв'язки: Glossary… (Ctrl+G) → Series Glossary... → New Empty Series Glossary..., Link or Import Series Glossary... або Unlink <назва>. Зв'язки зберігаються в series_glossary метаданих .uiproj (один шлях або список від найближчого) і йдуть перед глосаріями з тек. Файл у форматі glossary.json зв'язується там, де лежить, і редагується на місці. Будь-який інший JSON глосарію — документ серії {"terms": [...]} з renderings за джерелами, recommended, status, options, note, aliases — спершу конвертується в ~/.picoripi/series_glossaries/: recommended стає перекладом, кожен окремий варіант із джерел — варіантом (джерела й додаткові форми — як обґрунтування), options — ще варіантами, category — категорією; терміни agreed/resolved підтверджені, decision/proposed лишаються на перевірці, а початковий статус, ігри й причина йдуть у поле AI-нотаток.
• Вкладки: вікно Glossary показує Project Glossary і по одній вкладці Series: <назва> на рівень (назва теки для глосарію з теки, інакше ім'я файлу), з тією самою таблицею, пошуком, вкладками категорій і редактором. Виберіть терміни (Ctrl/Shift+клік) і натисніть Copy to Project Glossary у вкладці серії або Promote to Series Glossary у вкладці проєкту (за кількох рівнів меню питає, в який); термін, який уже є в іншому глосарії, отримує скопійований переклад і зберігає власні фрагменти й нотатки. Термін, який проєкт і глосарій серії перекладають по-різному, червоний в обох вкладках, а підказка показує інший переклад.
• У промптах AI: глосарій проєкту йде першим і має перевагу. Рядки серії додаються лише для термінів тексту, яких глосарій проєкту не перекладає, від найближчого рівня і кожен термін один раз, в окремому полі series_glossary (пакет) або розділі SERIES GLOSSARY (один рядок) з позначкою нижчого пріоритету.

• Побудова пише лише в глосарій проєкту; файл серії змінюється тільки через вкладку серії або Promote to Series Glossary. Термін, який глосарій серії вже переклав, засівається з цим перекладом (і його статусом), тож побудова не вирішує його знову. Ігрові терміни (види, ходи, предмети тощо) беруться з хука засівання плагіна; проєкт може засіяти файл серії без вікна командою python -I scripts/seed_series_glossary.py <project.uiproj> <файл серії>, яка додає лише відсутні терміни й не пише переклад.

• Засівання (Покемони): таблиці назв проєкту Покемонів (види, ходи, предмети, здібності, типи, класи тренерів) засівають файл серії: один термін на рядок, без перекладу. scripts/seed_series_glossary.py виконує це на копії; файл лишається вашим.

• Заповнити терміни з глосарію… (меню File): показує кожен рядок, чий увесь текст дорівнює терміну серії (теги порівнюються за видами тегів гри). Неперекладений рядок отримує переклад терміна, коли його теги й вікно відповідають; рядок з іншим перекладом лишається як є; два записи серії з різними перекладами одного терміна — конфлікт, і для нього нічого не записується. Fill the other projects of the series записує неперекладені рядки кожного іншого зареєстрованого проєкту в його резервну копію (saved_translations.json; першу копію збережено як saved_translations.before_terms.json); проєкт бере їх своєю дією Restore. Файли перекладу читаються першими, тож переклад, який там уже є, зберігається. Перевірку ширини виконано лише для відкритого проєкту.
• Редактор: терміни серії, яких немає в глосарії проєкту, стають збігами в перевірці перекладу рядка, щойно файл серії має для них переклад. Два глосарії серії, які перекладають один термін по-різному, позначаються Конфлікт на обох вкладках.

5. Translate the text (text)

Має вбудовані кнопки запуску прямо на правій панелі майстра: - Translate Story First (Chronological): перекладає репліки основного сюжету в хронологічному порядку, тож сюжетний текст готовий першим. - Translate Remaining Blocks (Semantic & System): перекладає меню, крамниці та системний текст після сюжету, з тим самим глосарієм і контекстом рядка. - Run Full Pipeline (Story ➔ Semantic): автоматичний запуск повного мультиагентного конвеєра (спочатку сюжет, потім решта блоків).

Переклад також можна запускати з редактора (AI Translate, правий клік по виділенню, кнопка AI на головному тулбарі або пункт Tools → AI Batch Translation ➔).

Статус: непорожні рядки, чий поточний текст відрізняється від оригіналу. Рядки, залишені ідентичними (імена, числа), навмисно недораховуються.

Див. 11. AI-переклад.

Додаток: автоматичний прохід глосарію докладно

Звідки запускається. Tools → Prepare Glossary…, крок майстра Prepare and enrich the glossary і кнопка у вікні глосарію ведуть в один маршрут. Внутрішні режими (seed, thorough, augment, translate) лишилися як будівельні блоки; запускати їх по черзі нікому не треба.

Файли. Глосарій — <тека проєкту>/glossary.json. Поруч прохід тримає glossary.scan.json: відбитки вже оброблених блоків. Це службовий стан інкрементального обходу, а не другий глосарій.

Область. Якщо позначено лише частину проєкту, глобальні структурні записи без прив'язки до блоку в частковий прохід не підмішуються. Блок із незмінним вмістом повторно не обходиться; Re-scan every selected block with AI запускає довгий повний обхід і все одно не перезаписує підтверджене людиною.

Що об'єднується. Точний нормалізований збіг приєднується до наявного запису, не чіпаючи підтверджених перекладів та описів. Нечіткий збіг сам ніколи не об'єднує — пару показано людині для рішення.

У вікні глосарію дані розділено: Description (чистий підсумковий опис, що йде в переклад), Proposed variants (кандидати, кожен із поясненням), AI notes and unresolved choices (спостереження обходу, альтернативні переклади, докази того, хто цей персонаж, можливі дублікати), Occurrences.

Звіт після проходу показує залишок, а не «готово»: записи, що чекають перегляду, записи з кількома варіантами, записи без перекладу чи опису, можливі дублікати. Review glossary відкриває чергу; Continue in editor повертає до перекладу, навіть коли черга не порожня.

Ручна перевірка проходу (десять хвилин, два невеликі блоки):

1. Запустіть прохід лише для двох блоків: seed → sweep → describe → translate ідуть без пауз.
2. У вікні глосарію опис і AI-нотатки — у різних областях; неоднозначний термін має кілька варіантів із різними поясненнями.
3. Запустіть ті самі блоки ще раз: нічого не обходиться. Змініть один рядок в одному блоці й повторіть: обходиться лише цей блок.
4. Підтвердьте переклад вручну й повторіть: він лишається. Увімкніть повний re-scan: джерела перечитано, підтверджений запис усе одно лишається.

Рекомендований порядок

1. Markup
2. Merge Speakers (якщо в плагіна є speaker_attribution)
3. Context Builder крок 1 (2–3 за бажанням)
4. Prepare Glossary
5. Перекладати в редакторі, з глосарієм + спікером + сценою в промпті

Кожен інструмент усе одно можна відкрити з Tools без майстра.

Чого не робити

• Не починайте Merge Speakers без розміченого скрипта (крок муситиме вгадувати з ALL-CAPS).
• Не запускайте автопрохід глосарія, чекаючи, що він зупиниться на review.
• Не ставте Parallel Requests вище за кількість Active-акаунтів проксі.
• Не трактуйте “N / M rows translated” як оцінку QA; правильні ідентичні рядки виглядають неперекладеними.
• Не документуйте і не чекайте пунктів, які є лише в docs/PIPELINE_ROADMAP.md — це план, не цей майстер.