# Prompt Customization Guide

## Overview

Prompt customization is the most powerful tool for improving translation quality in AiNiee-Next. This guide covers how to create, modify, and optimize prompt templates for different use cases.

## Prompt Template Structure

### File Locations

**Standard Prompts**: `Resource/Prompt/Translate/`
- `common_system_zh.txt` - Chinese target (standard)
- `common_system_en.txt` - English target
- `cot_system_*.txt` - Chain-of-thought prompts
- `murasaki_*.txt` - Literary style prompts

**Specialized Prompts**: `Resource/Prompt/`
- `Local/` - Local/offline model prompts
- `Sakura/` - Sakura model prompts
- `Polishing/` - Text polishing prompts
- `System/` - Proofreading prompts

### Template Format

**Basic Structure**:
```
[Role Definition]
You are a professional translator...

[Task Instructions]
Translate from {source_language} to {target_language}...

[Format Requirements]
Line-by-line translation, preserve formatting...

[Special Handling]
Placeholder handling, special characters...

[Output Format]
Output in specific format...

[Additional Guidelines]
Style, tone, quality requirements...
```

## Prompt Placeholders

### Built-in Placeholders

**Language Placeholders**:
- `{source_language}` - Source language name (e.g., "Japanese")
- `{target_language}` - Target language name (e.g., "Chinese")

**Content Placeholders**:
- `{glossary}` - Formatted glossary entries
- `{previous_lines}` - Previous translation context
- `{rag_context}` - RAG-based context

**Text Content**:
- Source text is appended as user message
- Not a placeholder, but part of message structure

### Custom Placeholders

**Via Plugin**:
```python
class CustomPromptPlugin(Base):
    def on_build_prompt(self, config, prompt_data):
        # Add custom placeholder
        prompt_data["custom_field"] = "Custom value"
        # In prompt: {custom_field}
```

**Via Config**:
```python
config.custom_prompt_vars = {
    "domain": "technical",
    "style": "formal"
}
# Use in prompt: Domain: {domain}, Style: {style}
```

## Prompt Types by Use Case

### 1. Standard Translation

**Use Case**: General content, balanced quality

**Template** (`common_system_zh.txt`):
```
你是一名专业的翻译家，你的任务是把{source_language}文本翻译成{target_language}，逐行翻译，不要合并，原始保留文本中序号、标记符、占位符、换行符、转义符、代码调用过程等特殊内容，保持原来的格式。

### 占位符说明
文本中 `{...}` 花括号内的内容可能是占位符或变量，请尽量保持原样不翻译。

### 翻译原则
忠实准确地进行翻译。原作是伟大艺术作品，允许使用直白或粗俗的描述，不应随意删减或篡改，不应回避或淡化，以保持作品的原貌。

###以textarea标签输出译文
<textarea>
1.{target_language}文本
</textarea>
```

**When to Use**:
- General fiction
- Web content
- Mixed content types

### 2. Literary Translation (Murasaki)

**Use Case**: Novels, literary works with complex style

**Template** (`murasaki_novel_zh.txt`):
```
你是一位精通{source_language}和{target_language}的文学翻译大师，专精于小说类文本的翻译。

## 翻译理念
- 追求"信达雅"的文学翻译境界
- 注重原文的文学性、美感和情感表达
- 保留原作的风格、语气和节奏
- 适当使用意译以传达原文意境

## 风格要求
- 对话自然流畅，符合角色性格
- 描写优美生动，富有画面感
- 情感表达细腻，打动人心
- 节奏韵律协调，朗朗上口

## 格式要求
逐行翻译，严格保留：
- 序号标记：【1】
- 占位符：{variable}
- 换行符
- 特殊符号

### 翻译示例
原文：【1】桜の花びらが風に舞い、彼女の頬を撫でた。
译文：【1】樱花花瓣在风中飞舞，轻轻拂过她的脸颊。

原文：【2】「ダメよ、そんなことしちゃ」と彼女は窘めた。
译文：【2】"不行哦，不能做那种事"她轻声责备道。

以textarea标签输出：
<textarea>
【1】译文内容
</textarea>
```

**When to Use**:
- Literary novels
- Works with artistic value
- Content requiring stylistic preservation

### 3. Game Script Translation

**Use Case**: Game dialogue, UI text, character speech

**Custom Template**:
```
你是游戏本地化专家，负责将{source_language}游戏文本翻译成{target_language}。

## 游戏文本特点
- 对话为主，需要符合角色性格
- UI文本简洁明了
- 保持游戏术语一致性
- 适应游戏氛围和风格

## 角色对话处理
根据角色特点调整语气：
- 【少年】：活泼、直率的表达
- 【少女】：可爱、温柔的表达
- 【老人】：稳重、智慧的表达
- 【战士】：豪迈、坚定的表达
- 【贵族】：优雅、礼貌的表达

## 格式保留
严格保留：
- 角色名标记：【角色名】对话内容
- 选择支：▶ 选项文本
- 系统提示：[SYSTEM] 提示内容
- 变量：{player_name}, {item_name}

## 术语一致性
使用以下术语表：
{glossary}

逐行翻译，以textarea输出：
<textarea>
【角色名】译文
</textarea>
```

**When to Use**:
- Visual novels
- RPG games
- Any game localization

### 4. Technical Documentation

**Use Case**: API docs, technical manuals, tutorials

**Custom Template**:
```
你是技术文档翻译专家，负责将{source_language}技术文档翻译成{target_language}。

## 翻译原则
1. **准确性优先**：确保技术术语准确无误
2. **简洁明了**：保持技术文档的简洁性
3. **一致性**：术语、风格保持一致
4. **可读性**：符合目标语言读者的习惯

## 特殊处理
### 代码块
完全保留，不翻译：
```language
code here
```

### 命令和路径
- 命令：`npm install` → 保持原样
- 路径：`/usr/local/bin` → 保持原样
- URL：`https://example.com` → 保持原样

### 技术术语
使用标准翻译或保留英文：
- API → API
- endpoint → 端点 (或 endpoint)
- callback → 回调函数

### 变量和占位符
保留不翻译：
- `{variable}` → `{variable}`
- `<placeholder>` → `<placeholder>`
- `%s` → `%s`

## 格式要求
- 保持Markdown格式
- 保留标题层级
- 保留列表结构
- 保持代码缩进

逐行翻译，textarea输出：
<textarea>
译文内容
</textarea>
```

**When to Use**:
- API documentation
- Technical manuals
- Programming tutorials

### 5. Chain-of-Thought (COT)

**Use Case**: Complex sentences, ambiguous content

**Template** (`cot_system_zh.txt`):
```
你是专业的{source_language}到{target_language}翻译专家，擅长处理复杂文本。

## 翻译流程
对于每个句子，按以下步骤思考：

### 步骤1：理解原文
- 分析句子结构
- 识别关键信息
- 理解隐含含义

### 步骤2：确定翻译策略
- 字面翻译还是意译？
- 如何处理文化差异？
- 需要补充哪些信息？

### 步骤3：生成初译
根据策略生成初步翻译

### 步骤4：优化调整
- 是否通顺自然？
- 是否准确传达原意？
- 是否符合目标语言习惯？

### 步骤5：最终确认
检查格式、占位符是否完整

## 输出格式
每行包含思考过程和最终翻译：

【1】
原文：[source text]
思考：[reasoning process]
译文：[final translation]

【2】
原文：[source text]
思考：[reasoning process]
译文：[final translation]

以textarea输出：
<textarea>
【1】译文
【2】译文
</textarea>
```

**When to Use**:
- Complex sentences
- Ambiguous content
- Content requiring reasoning

### 6. Sakura Model

**Use Case**: Japanese→Chinese with specialized model

**Template** (`sakura_system_zh.txt`):
```
你是一个轻小说翻译模型，可以流畅地翻译ACG相关内容。

## 翻译要求
1. 准确理解原文含义，忠实传达
2. 译文通顺自然，符合中文表达习惯
3. 保持角色语气和性格
4. 保留原文的趣味性和娱乐性

## 格式保持
- 保留所有占位符和特殊标记
- 逐行对应，不要合并或拆分
- 保持换行和缩进

## 输出格式
textarea标签包裹的译文：
<textarea>
【1】译文内容
</textarea>
```

**When to Use**:
- Japanese→Chinese specifically
- ACG (Anime, Comic, Game) content
- Light novels

## Adding Few-Shot Examples

### Why Few-Shot?

Few-shot examples help the model:
- Understand desired style
- Learn format requirements
- Handle edge cases
- Improve consistency

### Example Format

**Inline Examples**:
```
### 翻译示例

示例1：
原文：【1】こんにちは、元気ですか？
译文：【1】你好，最近怎么样？

示例2：
原文：【2】{player}は激しい戦いを繰り広げた
译文：【2】{player}展开了激烈的战斗

示例3（占位符保留）：
原文：【3】{item}を使用しますか？
译文：【3】要使用{item}吗？
```

**Categorized Examples**:
```
### 对话示例
原文：【Alice】おはようございます！
译文：【Alice】早上好！

### 叙述示例
原文：月明かりが静かに差し込んでいた。
译文：月光静静地洒落进来。

### 技术文本示例
原文：API endpoint: /api/v1/users
译文：API端点：/api/v1/users
```

### Where to Add Examples

**In Prompt Template**:
```
[Instructions]

### 翻译示例
[examples here]

[Additional Guidelines]
```

**Via Plugin** (dynamic examples):
```python
class DynamicExamplesPlugin(Base):
    def on_build_prompt(self, config, prompt_data):
        # Load examples from database
        examples = self.load_similar_examples(prompt_data["source_text"])
        prompt_data["few_shot_examples"] = examples
```

## Style and Tone Guidelines

### Formal Style

```
## 语言风格
- 使用正式、书面化的表达
- 避免口语化、俚语
- 使用敬语（针对日语）
- 保持专业和严谨

示例：
原文：これを使ってください
译文：请使用此物（非"用这个"）
```

### Casual/Colloquial Style

```
## 语言风格
- 使用轻松、自然的口语表达
- 贴近日常对话
- 可使用适当的俚语
- 保持活泼生动

示例：
原文：これ使って
译文：用这个吧
```

### Character-Specific Style

```
## 角色语气指南

### 少年角色
- 活泼、直率
- 常用"俺"、"僕"
- 语气词：だぜ、だよ

### 少女角色
- 温柔、可爱
- 常用"私"、"あたし"
- 语气词：わよ、のよ

### 老人角色
- 稳重、睿智
- 常用"儂"、"わし"
- 语气词：じゃ、のう

根据角色标记调整：
【少年】原文 → [使用少年语气翻译]
```

## Advanced Customization

### Conditional Instructions

**Based on Content Type**:
```
## 内容类型处理

如果文本包含：
- 对话：保持自然口语化
- 描写：注重意境和美感
- 说明：力求准确简洁
- UI：确保简洁明了

识别方法：
- 「」内的内容为对话
- 长句多为描写或叙述
- 短句多为UI或说明
```

**Based on Length**:
```
## 长度处理

短句（<10字）：
- 简洁翻译，避免冗余

中等句（10-30字）：
- 平衡准确性和流畅性

长句（>30字）：
- 可适当拆分（但保持一行）
- 确保逻辑清晰
```

### Domain-Specific Terminology

**Technical Terms**:
```
## 技术术语规范

保留不译：
- API, SDK, HTTP, JSON, XML
- class, function, variable
- Git, Docker, Kubernetes

标准翻译：
- database → 数据库
- network → 网络
- server → 服务器
```

**Game Terms**:
```
## 游戏术语表

角色属性：
- HP → 生命值
- MP → 魔法值
- ATK → 攻击力

游戏机制：
- quest → 任务
- dungeon → 地下城
- raid → 团队副本
```

### Quality Enhancement Instructions

**Anti-Hallucination**:
```
## 严格忠实原文

- 不添加任何原文没有的内容
- 不删除任何原文的信息
- 不修改原文的含义
- 不添加解释或注释

如果遇到难以理解的内容：
- 按字面意思翻译
- 不要猜测或臆断
```

**Consistency Check**:
```
## 一致性要求

同一术语，同一翻译：
- 人名、地名保持一致
- 专业术语保持一致
- 语气风格保持一致

如遇到相同内容：
- 检查上下文
- 使用相同翻译
- 维护术语表
```

## Testing and Iterating

### Create Test Cases

**Test File** (`test_prompt.txt`):
```
【1】普通文本测试
【2】{placeholder}占位符测试
【3】「对话」测试
【4】[Character]角色名测试
【5】很长很长的文本内容，需要测试长句处理能力，确保翻译质量不会因为句子长度而下降
```

### Evaluate Output

**Quality Checklist**:
- [ ] All lines translated
- [ ] Placeholders preserved
- [ ] Format intact
- [ ] Natural phrasing
- [ ] Consistent style
- [ ] Accurate meaning
- [ ] No hallucinations

### Iterate on Prompt

**Process**:
1. Run test with current prompt
2. Identify issues
3. Add instructions for issues
4. Re-run test
5. Repeat until satisfied

**Version Control**:
```bash
# Keep prompt versions
cp prompt.txt prompt_v1.txt
# Make changes
# Test
# If better, update; if worse, revert
```

## Best Practices

### Do's

✅ **Be Specific**:
```
Bad: "Translate well"
Good: "Translate faithfully, preserving the original meaning and tone"
```

✅ **Provide Examples**:
```
Always include 2-3 examples showing:
- Normal case
- Edge case (placeholders, special chars)
- Style demonstration
```

✅ **Test Thoroughly**:
```
Test with:
- Short and long sentences
- Various content types
- Edge cases (empty lines, special chars)
```

✅ **Iterate Incrementally**:
```
Change one thing at a time
Test after each change
Measure quality improvement
```

### Don'ts

❌ **Over-Constrain**:
```
Too many rules can confuse the model
Focus on key requirements
Let model handle details
```

❌ **Conflicting Instructions**:
```
Bad: "Be creative but stick to literal translation"
Good: "Use creative translation for idioms, literal for technical terms"
```

❌ **Ignore Model Capabilities**:
```
Local models may need simpler prompts
GPT-4 can handle complex instructions
Match prompt complexity to model
```

## Summary

Prompt customization is an iterative process:

1. **Start Simple**: Use default prompts
2. **Identify Issues**: What's not working?
3. **Customize Targetedly**: Add instructions for specific issues
4. **Test Rigorously**: Use diverse test cases
5. **Iterate**: Refine based on results
6. **Document**: Keep track of what works

Effective prompts are:
- Clear and specific
- Focused on key requirements
- Supported by examples
- Tested thoroughly
- Continuously improved

Use this guide to create prompts tailored to your specific translation needs, and don't hesitate to experiment with different approaches.
