scriveno 2.0.5

package/commands/scr/translate.md

@@ -0,0 +1,260 @@
+---
+description: Translate manuscript to target language with glossary and translation memory support.
+argument-hint: "<language> [--all] [--from <unit>] [--languages] [--add-language <lang>]"
+---
+
+# /scr:translate -- Manuscript Translation
+
+Translate the manuscript into a target language, one atomic unit at a time, using the translator agent with fresh context per unit. Loads glossary and translation memory into each unit's context for term consistency across the manuscript.
+
+## Usage
+
+```
+/scr:translate <language>           # Translate to a specific language (e.g., fr, ja, ar)
+/scr:translate --all                # Translate to all configured target languages
+/scr:translate --from <unit>        # Resume translation from a specific unit
+/scr:translate --languages          # List configured target languages
+/scr:translate --add-language <lang> # Add a target language to config
+```
+
+## Instruction
+
+You are a **translation orchestrator**. Your job is to manage the per-unit translation pipeline, ensuring each unit is translated with full context (glossary, translation memory, style guide, character data) by invoking the translator agent in fresh context for every atomic unit.
+
+---
+
+### STEP 1: LOAD CONTEXT
+
+Load the following project files:
+
+- `.manuscript/config.json` -- to get `source_language`, `target_languages`, `name_handling`, `measurement_system` from the `translation` section
+- Scriveno's installed/shared `CONSTRAINTS.json` (global `~/.scriveno/data/CONSTRAINTS.json` or project `.scriveno/data/CONSTRAINTS.json`) -- to check prerequisites
+
+---
+
+### STEP 2: HANDLE FLAGS
+
+**If `--languages` flag:**
+
+Read `.manuscript/config.json` and display the configured target languages:
+
+> **Configured target languages:**
+> - French (fr)
+> - Japanese (ja)
+>
+> **Source language:** English (en)
+>
+> To add a language: `/scr:translate --add-language <lang>`
+
+Then **stop**.
+
+**If `--add-language <lang>` flag:**
+
+1. Read `.manuscript/config.json`
+2. Add the language code to the `translation.target_languages` array
+3. Write the updated config back
+4. Confirm:
+
+> **Added target language:** [language name] ([code])
+>
+> Current target languages: [list all]
+>
+> **Next steps:**
+> - Create a glossary: `/scr:translation-glossary [lang]`
+> - Start translating: `/scr:translate [lang]`
+
+Then **stop**.
+
+---
+
+### STEP 3: VALIDATE
+
+**Validate target language:**
+
+If a specific language was provided (not `--all`):
+1. Check if it is in the `translation.target_languages` array in config.json
+2. If not:
+
+> **"[lang]" is not a configured target language.**
+>
+> Configured languages: [list]
+>
+> To add it: `/scr:translate --add-language [lang]`
+
+Then **stop**.
+
+**Check prerequisite: complete draft**
+
+Check that drafts exist for all units in OUTLINE.md. Look for files in `.manuscript/drafts/body/` matching the units listed in `.manuscript/OUTLINE.md`.
+
+If drafts are missing:
+
+> **Translation requires a complete draft.** The following units have no draft:
+> - [list missing units]
+>
+> Complete drafting first with `/scr:draft` or `/scr:autopilot`.
+
+Then **stop**.
+
+---
+
+### STEP 4: PREPARE TRANSLATION ENVIRONMENT
+
+1. **Create directory structure** for the target language(s):
+
+```
+.manuscript/translation/{lang}/
+  drafts/
+  front-matter/
+  back-matter/
+  metadata/
+```
+
+2. **Load glossary** (if it exists):
+
+Read `.manuscript/translation/GLOSSARY-{lang}.md`. If it does not exist:
+
+> **Glossary recommended.** No glossary found for [language]. A glossary ensures consistent translation of character names, place names, and key terms.
+>
+> Create one now: `/scr:translation-glossary [lang]`
+>
+> Continuing without glossary -- new terms will be flagged by the translator agent.
+
+3. **Load translation memory** (if it exists):
+
+Read `.manuscript/translation/translation-memory.json`. If it does not exist, proceed without -- the translation memory will be built from completed translations.
+
+4. **Read OUTLINE.md** for the ordered list of units.
+
+5. **If `--from <unit>` flag:** Find the specified unit in OUTLINE.md and start from that position. Skip all units before it.
+
+---
+
+### STEP 5: TRANSLATE PER UNIT
+
+**If `--all` flag:** Loop through each language in `target_languages`, running the full translation pipeline for each. Translate one language completely before starting the next.
+
+For each unit in OUTLINE.md (or from `--from` position):
+
+**5a. Gather context for this unit:**
+
+1. **Source text:** Read `.manuscript/drafts/body/{unit}-DRAFT.md` (or the appropriate draft path from OUTLINE.md)
+2. **STYLE-GUIDE.md:** Read `.manuscript/STYLE-GUIDE.md`
+3. **GLOSSARY-{lang}.md:** Read `.manuscript/translation/GLOSSARY-{lang}.md` (if it exists)
+4. **Translation memory excerpt:** From `translation-memory.json`, extract segments that match content in this unit (if TM exists). Look for source sentences that appear in this unit's text. Include the top 20 most relevant matches.
+5. **CHARACTERS.md excerpt:** Read `.manuscript/CHARACTERS.md` (or FIGURES.md for sacred works) and extract only the characters who appear in this unit's source text. Match character names against the source text to determine relevance.
+6. **Previous translated unit tail:** Read the last 200 words of the previously translated unit from `.manuscript/translation/{lang}/drafts/` (if any prior unit exists)
+7. **Target language config:** Language code, `name_handling`, `measurement_system` from config.json
+
+**5b. Sacred mode detection:**
+
+If `.manuscript/config.json` has a `work_type` whose group is `sacred` (check against `CONSTRAINTS.json` work_types), read the top-level sacred profile keys from config.json and construct a `sacred_mode` object to pass to the translator agent. For older projects only, if a value is absent at top level and present under a nested `sacred` object, use the nested value as a legacy fallback:
+
+```json
+{
+  "sacred_mode": true,
+  "translation_philosophy": "[from top-level config.json translation_philosophy]",
+  "canonical_alignment": "[from top-level config.json canonical_alignment]",
+  "preserve_source_terms": "[from top-level config.json preserve_source_terms]",
+  "transliteration_style": "[from top-level config.json transliteration_style]",
+  "liturgical_preservation": "[from top-level config.json liturgical_preservation]"
+}
+```
+
+For sacred works, the translation philosophy from config.json determines how the translator approaches each passage. Use `/scr:settings` to change `translation_philosophy`.
+
+If the work type group is not `sacred`, skip this step -- the translator operates in standard mode.
+
+**5c. Invoke translator agent:**
+
+Invoke the translator agent (`agents/translator.md`) with fresh context, providing all gathered files. For sacred works, include the `sacred_mode` object alongside the standard context. The agent translates the unit and writes to `.manuscript/translation/{lang}/drafts/{unit}-DRAFT.md`.
+
+**Fresh context per unit is mandatory.** Each translator invocation is independent -- this prevents translation drift, glossary inconsistency, and register collapse across a long manuscript.
+
+**5d. Post-unit processing:**
+
+After each unit translation:
+
+1. **Check for new terms:** If the translator flagged new terms not in the glossary, collect them:
+
+> **New terms flagged in [unit]:**
+> - "[term]" -> "[suggested translation]" ([category])
+
+2. **Report progress:**
+
+> Translated [unit]: [source_word_count] source words -> [target_word_count] target words ([ratio]x)
+
+3. **Update running totals:** Track total source words, total target words, units completed, new terms flagged.
+
+---
+
+### STEP 6: COMPLETION REPORT
+
+After all units are translated, show a summary:
+
+> **Translation complete: [language name]**
+>
+> **Units translated:** [count] / [total]
+> **Source word count:** [total source words]
+> **Target word count:** [total target words]
+> **Expansion ratio:** [target/source]x
+>
+> **Glossary compliance:**
+> - Terms from glossary used: [count]
+> - New terms flagged: [count] (review with `/scr:translation-glossary [lang] --review`)
+>
+> **Translation memory:**
+> - TM segments reused: [count]
+> - New segments available: [count] (build TM with `/scr:translation-memory [lang] --build`)
+>
+> **Next steps:**
+> - Review new terms: `/scr:translation-glossary [lang] --review`
+> - Build translation memory: `/scr:translation-memory [lang] --build`
+> - Cultural adaptation review: `/scr:cultural-adaptation [lang]`
+> - Back-translate to verify: `/scr:back-translate [lang]`
+> - Export translation: `/scr:export --format [format] --language [lang]`
+
+## Response Contract
+
+Every writer-facing response must end with one to four next-command suggestions. Each suggestion must include a short explanation of what that path will do.
+
+Use this format:
+
+```markdown
+Next commands:
+- `/scr:...`: One short sentence explaining what this path will do.
+- `/scr:...`: One short sentence explaining what this alternate path will do.
+```
+
+If exactly one path is clearly best, provide one suggestion. If two, three, or four useful paths exist, show them as alternatives. Do not force a linear path when the writer has a real choice.
+
+If the writer seems unsure or no specific next command is obvious, include this default option:
+
+```markdown
+Next commands:
+- `/scr:next`: Inspect the project state and choose the right next step.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.
+
+## Tone
+
+**Progress updates:** Concise, one line per unit.
+- "Translated chapter 3, scene 2: 1,247 -> 1,389 words (1.11x)"
+- "Skipping chapter 5 -- already translated"
+
+**Warnings:** Actionable.
+- "3 new terms not in glossary -- review after translation completes"
+
+**Never show** (unless `developer_mode` is `true` in config.json):
+- File paths
+- Git terminology
+- Technical jargon about agent context or invocation
+
+## Anti-patterns
+
+- **NEVER** translate multiple units in a single agent context -- fresh context per unit is mandatory
+- **NEVER** skip the glossary check -- term consistency is the translator's primary constraint
+- **NEVER** translate without STYLE-GUIDE.md loaded -- voice must survive translation
+- **NEVER** overwrite an existing translation without warning -- if `.manuscript/translation/{lang}/drafts/{unit}-DRAFT.md` already exists, ask before replacing
+- **NEVER** ignore new terms flagged by the translator -- they must be reviewed and added to the glossary

package/commands/scr/translation-glossary.md

@@ -0,0 +1,298 @@
+---
+description: Create and manage bilingual term glossary for consistent translation.
+argument-hint: "<language> [--add <term> --translation <value>] [--import] [--review] [--category <cat>]"
+---
+
+# /scr:translation-glossary -- Glossary Management
+
+Create and manage bilingual translation glossaries. Glossaries ensure consistent translation of character names, place names, invented terms, titles, recurring phrases, and cultural references across the manuscript.
+
+Glossaries are stored as human-readable markdown tables in `.manuscript/translation/GLOSSARY-{lang}.md` -- version-controlled and easy to review.
+
+## Usage
+
+```
+/scr:translation-glossary <language>                           # Create glossary (or show existing)
+/scr:translation-glossary <language> --add <term> --translation <value>  # Add a single entry
+/scr:translation-glossary <language> --add <term> --translation <value> --category <cat>  # Add with category
+/scr:translation-glossary <language> --import                  # Bulk import terms
+/scr:translation-glossary <language> --review                  # Review glossary and find missing terms
+```
+
+## Instruction
+
+You are a **glossary manager**. Your job is to build and maintain bilingual term glossaries that the translator agent uses for consistent translation.
+
+---
+
+### STEP 1: LOAD CONTEXT
+
+Load the following project files:
+
+- `.manuscript/config.json` -- to get `target_languages`, `name_handling`, `measurement_system` from the `translation` section
+- `.manuscript/CHARACTERS.md` (or `FIGURES.md` for sacred works) -- character names to include in glossary
+- `.manuscript/WORLD.md` (if exists) -- place names and world-specific terms
+
+If no language argument is provided:
+
+> **Which language?**
+>
+> Configured target languages: [list from config.json]
+>
+> Specify a language: `/scr:translation-glossary <lang>`
+
+Then **stop**.
+
+Validate that the specified language is in the `target_languages` array. If not:
+
+> **"[lang]" is not a configured target language.** Add it with `/scr:translate --add-language [lang]` first.
+
+Then **stop**.
+
+---
+
+### STEP 2: ROUTE BY MODE
+
+Determine the mode based on flags:
+
+| Flags | Mode |
+|-------|------|
+| No flags | Create mode (if no glossary exists) or Display mode (if glossary exists) |
+| `--add <term> --translation <value>` | Add mode |
+| `--import` | Import mode |
+| `--review` | Review mode |
+
+---
+
+### MODE: CREATE (no GLOSSARY-{lang}.md exists)
+
+Scan the manuscript for translatable terms and build the initial glossary.
+
+**Step 1: Scan for terms**
+
+Read the following sources and extract terms that need consistent translation:
+
+1. **Character names** from CHARACTERS.md (or FIGURES.md for sacred works):
+   - Extract all character names, nicknames, titles
+   - Category: `character_name`
+
+2. **Place names** from WORLD.md (if it exists):
+   - Extract all location names, realm names, geographical features
+   - Category: `place_name`
+
+3. **Manuscript scan** -- Read through draft files in `.manuscript/drafts/body/` and identify:
+   - Invented terms and neologisms (words not in standard dictionaries)
+   - Category: `invented_term`
+   - Recurring titles and honorifics (e.g., "Lord," "Master," "Professor")
+   - Category: `title_honorific`
+   - Recurring phrases that appear 3+ times and carry specific meaning
+   - Category: `recurring_phrase`
+   - Cultural references specific to the work's setting
+   - Category: `cultural_reference`
+   - Brand names or proper nouns
+   - Category: `brand_name`
+
+**Step 2: Generate translations based on name_handling config**
+
+For each extracted term, provide a default translation:
+
+- **name_handling = `keep_original`:** Character names default to original spelling. Add transliteration in Notes column if the target language uses a different script.
+- **name_handling = `transliterate`:** Character names are transliterated into the target language's script/phonology.
+- **name_handling = `localize`:** Character names are given culturally equivalent names in the target language (e.g., John -> Jean, William -> Guillaume).
+
+For non-name terms (invented terms, phrases, cultural references): provide a contextually appropriate translation.
+
+**Step 3: Write glossary**
+
+Create the directory if needed:
+
+```
+mkdir -p .manuscript/translation/
+```
+
+Write the glossary as a markdown table to `.manuscript/translation/GLOSSARY-{lang}.md`:
+
+```markdown
+# Translation Glossary: [Language Name]
+
+**Source language:** [source_language from config]
+**Target language:** [language name] ([code])
+**Name handling:** [name_handling setting]
+**Last updated:** [date]
+
+## Terms
+
+| Source Term | Translation | Category | Notes |
+|-------------|-------------|----------|-------|
+| Marcus | Marcus | character_name | Original kept (keep_original) |
+| The Wandering City | La Cite Errante | place_name | |
+| chronoshifter | chronodecaleur | invented_term | Compound: chrono + shifter |
+| "Break the seal" | "Briser le sceau" | recurring_phrase | Ritual context |
+| Lord Commander | Seigneur Commandant | title_honorific | Military rank |
+
+## Categories
+
+- **character_name** -- Character names, nicknames, aliases
+- **place_name** -- Locations, realms, geographical features
+- **invented_term** -- Made-up words, neologisms, world-specific vocabulary
+- **title_honorific** -- Titles, ranks, forms of address
+- **recurring_phrase** -- Phrases that appear multiple times with specific meaning
+- **cultural_reference** -- Setting-specific cultural elements
+- **brand_name** -- Proper nouns, organization names
+
+## Usage Notes
+
+This glossary is loaded into the translator agent's context for every unit. Terms listed here MUST be used exactly as specified. To update a translation, edit this file directly or use `/scr:translation-glossary [lang] --add`.
+```
+
+Report:
+
+> **Glossary created for [language]:** `.manuscript/translation/GLOSSARY-[lang].md`
+>
+> **Terms catalogued:**
+> - [count] character names
+> - [count] place names
+> - [count] invented terms
+> - [count] titles/honorifics
+> - [count] recurring phrases
+> - [count] cultural references
+>
+> **Review the glossary** to verify translations before starting translation:
+> `/scr:translation-glossary [lang] --review`
+
+---
+
+### MODE: DISPLAY (GLOSSARY-{lang}.md exists, no flags)
+
+Read and display the existing glossary:
+
+> **Translation Glossary: [Language]**
+>
+> [Display the markdown table]
+>
+> **[count] terms total**
+>
+> **Actions:**
+> - Add a term: `/scr:translation-glossary [lang] --add <term> --translation <value>`
+> - Review for missing terms: `/scr:translation-glossary [lang] --review`
+> - Bulk import: `/scr:translation-glossary [lang] --import`
+
+---
+
+### MODE: ADD (`--add <term> --translation <value>`)
+
+Add a single term to the existing glossary.
+
+1. Read the existing GLOSSARY-{lang}.md
+2. Check if the term already exists:
+   - If yes: Ask whether to update the existing translation or keep it
+   - If no: Add to the table
+3. Determine category:
+   - If `--category <cat>` flag provided: use that category
+   - If not: infer from context (check CHARACTERS.md for character names, WORLD.md for places, etc.)
+4. Append the new row to the glossary table
+5. Write the updated file
+
+> **Added to glossary:** "[source term]" -> "[translation]" ([category])
+
+---
+
+### MODE: IMPORT (`--import`)
+
+Bulk import terms from a list provided by the writer.
+
+1. Read the existing GLOSSARY-{lang}.md (or create one if it doesn't exist)
+2. Prompt the writer to provide terms in one of these formats:
+
+> **Provide your terms in any of these formats:**
+>
+> **Simple list** (translations will be suggested):
+> ```
+> chronoshifter
+> The Wandering City
+> Lord Commander
+> ```
+>
+> **Term + translation pairs:**
+> ```
+> chronoshifter | chronodecaleur
+> The Wandering City | La Cite Errante
+> Lord Commander | Seigneur Commandant
+> ```
+>
+> **Full table rows:**
+> ```
+> chronoshifter | chronodecaleur | invented_term | Compound word
+> ```
+
+3. For simple lists: generate suggested translations using the same name_handling rules as Create mode
+4. Show the proposed entries for writer approval
+5. On approval: append all entries to the glossary and write the updated file
+
+> **Imported [count] terms to glossary.**
+
+---
+
+### MODE: REVIEW (`--review`)
+
+Review the glossary for completeness and consistency.
+
+1. Read the existing GLOSSARY-{lang}.md
+2. Scan the manuscript for terms that SHOULD be in the glossary but are NOT:
+   - Character names from CHARACTERS.md not in glossary
+   - Place names from WORLD.md not in glossary
+   - Any terms flagged as "NEW TERM" in translated draft files
+   - Invented terms or proper nouns found in drafts but missing from glossary
+3. Check for potential inconsistencies:
+   - Same source term with different translations
+   - Similar terms that might confuse the translator (e.g., "Lord" vs "Lord Commander")
+
+Report:
+
+> **Glossary Review: [Language]**
+>
+> **Coverage:**
+> - [count] terms in glossary
+> - [count] character names covered / [total] in CHARACTERS.md
+> - [count] place names covered / [total] in WORLD.md
+>
+> **Missing terms (found in manuscript but not in glossary):**
+> - "[term]" -- appears [count] times in manuscript
+> - "[term]" -- appears [count] times in manuscript
+>
+> **Potential inconsistencies:**
+> - "[term]" has no translation yet
+>
+> **Actions:**
+> - Add missing terms: `/scr:translation-glossary [lang] --add <term> --translation <value>`
+> - Bulk add: `/scr:translation-glossary [lang] --import`
+
+## Anti-patterns
+
+- **NEVER** create a glossary without checking CHARACTERS.md first -- character names are the highest priority for consistency
+- **NEVER** auto-translate names when `name_handling` is `keep_original` -- names stay in original form
+- **NEVER** overwrite an existing glossary without asking -- always append or update
+- **NEVER** leave the glossary in an invalid markdown table format -- the translator agent parses it
+
+## Response Contract
+
+Every writer-facing response must end with one to four next-command suggestions. Each suggestion must include a short explanation of what that path will do.
+
+Use this format:
+
+```markdown
+Next commands:
+- `/scr:...`: One short sentence explaining what this path will do.
+- `/scr:...`: One short sentence explaining what this alternate path will do.
+```
+
+If exactly one path is clearly best, provide one suggestion. If two, three, or four useful paths exist, show them as alternatives. Do not force a linear path when the writer has a real choice.
+
+If the writer seems unsure or no specific next command is obvious, include this default option:
+
+```markdown
+Next commands:
+- `/scr:next`: Inspect the project state and choose the right next step.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.