translation

Translation Guidelines

This file provides guidance to agents when working with translations in this repository.

For the translation workflow, use the /add-missing-translations command or see .kilocode/workflows/add-missing-translations.md.

1. SUPPORTED LANGUAGES AND LOCATION

Localize all strings into the following locale files: ar, ca, cs, de, en, es, fr, hi, id, it, ja, ko, nl, pl, pt-BR, ru, sk, th, tr, uk, vi, zh-CN, zh-TW
The VSCode extension has two main areas that require localization:
- Core Extension: src/i18n/locales/, src/package.nls.json, src/package.nls..json (extension backend)
- WebView UI: webview-ui/src/i18n/locales/ (user interface)

2. VOICE, STYLE AND TONE

Always use informal speech (e.g., "du" instead of "Sie" in German) for all translations
Maintain a direct and concise style that mirrors the tone of the original text
Carefully account for colloquialisms and idiomatic expressions in both source and target languages
Aim for culturally relevant and meaningful translations rather than literal translations
Preserve the personality and voice of the original content
Use natural-sounding language that feels native to speakers of the target language
Don't translate the word "token" as it means something specific in English that all languages will understand
Don't translate domain-specific words (especially technical terms like "Prompt") that are commonly used in English in the target language

3. CORE EXTENSION LOCALIZATION (src/)

Located in src/i18n/locales/
NOT ALL strings in core source need internationalization - only user-facing messages
Internal error messages, debugging logs, and developer-facing messages should remain in English
The t() function is used with namespaces like 'core:errors.missingToolParameter'
Be careful when modifying interpolation variables; they must remain consistent across all translations
Some strings in formatResponse.ts are intentionally not internationalized since they're internal
When updating strings in core.json, maintain all existing interpolation variables
Check string usages in the codebase before making changes to ensure you're not breaking functionality

4. WEBVIEW UI LOCALIZATION (webview-ui/src/)

Located in webview-ui/src/i18n/locales/
Uses standard React i18next patterns with the useTranslation hook
All user interface strings should be internationalized
Always use the Trans component with named components for text with embedded components

example:

"changeSettings": "You can always change this at the bottom of the <settingsLink>settings</settingsLink>",

  <Trans
    i18nKey="welcome:telemetry.changeSettings"
    components={{
      settingsLink: <VSCodeLink href="#" onClick={handleOpenSettings} />
    }}
  />

5. TECHNICAL IMPLEMENTATION

Use namespaces to organize translations logically
Handle pluralization using i18next's built-in capabilities
Implement proper interpolation for variables using {{variable}} syntax
Don't include defaultValue. The en translations are the fallback
Always use apply_diff instead of write_to_file when editing existing translation files (much faster and more reliable)
When using apply_diff, carefully identify the exact JSON structure to edit to avoid syntax errors
Placeholders (like {{variable}}) must remain exactly identical to the English source to maintain code integration and prevent syntax errors

6. WORKFLOW AND APPROACH

First add or modify English strings, then ask for confirmation before translating to all other languages
Use this process for each localization task:
1. Identify where the string appears in the UI/codebase
2. Understand the context and purpose of the string
3. Update English translation first
4. Use the <search_files> tool to find JSON keys that are near new keys in English translations but do not yet exist in the other language files for <apply_diff> SEARCH context
5. Create appropriate translations for all other supported languages utilizing the search_files result using <apply_diff> without reading every file.
6. Do not output the translated text into the chat, just modify the files.
7. Validate your changes with the missing translations script
Flag or comment if an English source string is incomplete ("please see this...") to avoid truncated or unclear translations
For UI elements, distinguish between:
- Button labels: Use short imperative commands ("Save", "Cancel")
- Tooltip text: Can be slightly more descriptive
Preserve the original perspective: If text is a user command directed at the software, ensure the translation maintains this direction, avoiding language that makes it sound like an instruction from the system to the user

7. COMMON PITFALLS TO AVOID

Switching between formal and informal addressing styles - always stay informal ("du" not "Sie")
Translating or altering technical terms and brand names that should remain in English
Modifying or removing placeholders like {{variable}} - these must remain identical
Translating domain-specific terms that are commonly used in English in the target language
Changing the meaning or nuance of instructions or error messages
Forgetting to maintain consistent terminology throughout the translation

8. QUALITY ASSURANCE

Maintain consistent terminology across all translations
Respect the JSON structure of translation files
Watch for placeholders and preserve them in translations
Be mindful of text length in UI elements when translating to languages that might require more characters
Use context-aware translations when the same string has different meanings
Always validate your translation work by running the missing translations script:
```
node scripts/find-missing-translations.js
```
Address any missing translations identified by the script to ensure complete coverage across all locales

9. TRANSLATOR'S CHECKLIST

✓ Used informal tone consistently ("du" not "Sie")
✓ Preserved all placeholders exactly as in the English source
✓ Maintained consistent terminology with existing translations
✓ Kept technical terms and brand names unchanged where appropriate
✓ Preserved the original perspective (user→system vs system→user)
✓ Adapted the text appropriately for UI context (buttons vs tooltips)

Language-Specific Guidelines

German (de) Translation Guidelines

Key Rule: Always use informal speech ("du" form) in all German translations without exception.

Quick Reference

Category	Formal (Avoid)	Informal (Use)	Example
Pronouns	Sie	du	you
Possessives	Ihr/Ihre/Ihrem	dein/deine/deinem	your
Verbs	können Sie, müssen Sie	kannst du, musst du	you can, you must
Imperatives	Geben Sie ein, Wählen Sie	Gib ein, Wähle	Enter, Choose

Technical terms like "API", "token", "prompt" should not be translated.

Simplified Chinese (zh-CN) Translation Guidelines

Key Terminology

English Term	Preferred (zh-CN)	Avoid	Context/Notes
API Cost	API Fee	API Cost	Finance-related terminology
Tokens	Token	Tokens	Keep abstract terminology
Token Usage	Token Usage	Token usage	Technical unit of measurement
Cache	Cache	Cache	Conciseness first
Context	Context		Keep abstract terminology
Context Menu	Right-click menu	Context menu	Technical terminology accuracy
Context Window	Context window		Technical terminology accuracy
Proceed While Running	Force continue	Runtime continue	Operation command
Enhance Prompt	Enhanced prompt	Optimize prompt	AI-related feature
Auto-approve	Auto-approve	Always approve	Permission-related terminology
Checkpoint	Save point	Checkpoint/snapshot	Unified technical concept
MCP Server	MCP Service	MCP Server	Technical component
Human Relay	Human-assisted mode	Human relay	Clear feature description
Network Timeout	Request timeout	Network timeout	More accurate description
Terminal	Terminal	Command line	Unified technical terminology
diff	Diff update	Diff/patch	Code change
prompt caching	Prompt cache	Prompt cache	AI feature
computer use	Computer interaction	Computer use	Technical capability
rate limit	API request rate limit	Rate limit	API control
Browser Session	Browser session	Browser process	Technical concept
Run Command	Run command	Execute command	Action verb
power steering mode	Enhanced steering mode	Power steering mode	Avoid literal translation
Boomerang Tasks	Task breakdown	Boomerang task	Avoid literal translation

Formatting Rules

Mixed Chinese and English
- Add spaces: add spaces between Chinese and English/numbers, such as "API 费用" (not "API费用")
- Unit format: time units are standardized as "15秒", "1分钟" (not "15 seconds", "1 minute")
- Number range: "已使用: {{used}} / {{total}}"
- Technical symbols remain as-is: "{{amount}} tokens"→"{{amount}}"
Punctuation
- Use Chinese full-width punctuation
- Use Chinese enumeration comma for list items: "创建、编辑文件"
UI text optimization
- Button text: use concise verbs, such as "展开" is better than "查看更多"
- Operation instructions: use step-by-step instructions (1. 2. 3.) instead of long paragraphs
- Error prompt: use "确认删除？此操作不可逆" instead of "Are you sure...?"
- Keep operation instructions concise: "Shift+drag files" is better than a long description.
- Keep button text to 2-4 Chinese characters: "Expand" is better than "View more".
Technical description
- Keep English abbreviations: e.g., "MCP" is not translated.
- Unify terminology: use the same translation for the same concept throughout the system.
- Split long sentences into short sentences.
- Convert passive voice to active voice.
- Unify feature names: "computer interaction" is better than "computer use".
- Parameter description: "differential update" is better than "diff/patch".
Variable placeholders
- Keep the original format:{{variable}}
- Put the Chinese explanation outside the variable: "Token usage: {{used}}"

UI Element Translation Standards

Buttons
- Confirmation type: Confirm/Cancel/Apply/Save
- Action type: Add/Delete/Edit/Export
- State type: Enable/Disable/Expand/Collapse
- Length limit: 2-4 Chinese characters
Menus
- Main menu: File/Edit/View/Help
- Submenu: use ">" to connect, e.g., "File>Open"
- Keyboard shortcuts: keep English, e.g., "Ctrl+S"
Labels
- Setting item: describe the function, e.g., "Auto-save interval"
- Status prompt: concise and clear, e.g., "Processing..."
- Unit description: put it in parentheses, e.g., "Timeout (seconds)"
Tooltips
- Feature description: concise description, e.g., "Copy selected content"
- Operation guidance: clear steps, e.g., "Double-click to edit the cell"
- Length limit: no more than 50 Chinese characters
Dialogs
- Title: describe the purpose of the dialog
- Body: explain in paragraphs
- Buttons: use verbs, e.g., "Confirm deletion"

Contextual Translation Principles

Adjust according to UI position
- Button text: concise verbs (e.g., "Expand", "Collapse")
- Setting item: descriptive (e.g., "Auto-approve write operations")
- Help text: complete explanation (e.g., "When enabled, automatically creates task save points for easy backtracking and modification")
Technical documentation style
- Use active voice: e.g., "automatically create and edit files"
- Avoid colloquial expressions
- Use bullet points to explain complex features
- Explain the operation result: e.g., "no secondary confirmation required"
- Clear parameter description: e.g., "delay for a period before automatically approving writes"
Brand/product names
- Keep English brand names
- Keep technical terminology consistent
- Keep English proper nouns: e.g., "Amazon Bedrock ARN"
User operations
- Unify action verbs:
  - "Click"→"点击"
  - "Type"→"输入"
  - "Scroll"→"滚动"
- Button states:
  - "Enabled"→"已启用"
  - "Disabled"→"已禁用"

Technical Documentation Guidelines

Technical terminology
- Uniformly use "Token" rather than "令牌"
- Keep English proper nouns: e.g., "Model Context Protocol"
- Unified feature naming: e.g., "computer function calling" is better than "computer use"
API Documentation
- Endpoint: keep the original path
- Parameter descriptions: present in table form
- Examples: preserve code formatting
- Parameter labels:
  - Clear units: e.g., "maximum output Token count"
  - Complete range description: e.g., "the total Token count the model can process"
Code-related translation
- Code comments:
  - Preserve technical terms: e.g., "// Initialize MCP client"
  - Brief description: e.g., "check whether the file exists"
- Error messages:
  - Include error code: e.g., "Error 404: file not found"
  - Provide a solution: e.g., "please check file permissions"
- Command line:
  - Preserve native commands: e.g., "git commit -m 'message'"
  - Parameter descriptions: e.g., "-v: show detailed output"
Configuration Guide
- Setting item naming: e.g., "Enable prompt caching"→"启用提示词缓存"
- Price description:
  - Unified units: e.g., "cost per million Tokens"
  - Explain the impact: e.g., "this affects the cost of generated content and completions"
- Operating instructions:
  - Use numbered steps: e.g., "1. Register a Google Cloud account"
  - Consistent step verbs: e.g., "Install and configure the Google Cloud CLI tool"

Common Patterns

Original	Avoid	Preferred
`"dragFiles"`	`"按住shift拖动文件"`	`"Shift+拖拽文件"`
`"description"`	`"启用后，Kilo Code 将能够与 MCP 服务器交互以获取高级功能。"`	`"启用后 Kilo Code 可与 MCP 服务交互获取高级功能。"`
`"cannotUndo"`	`"此操作无法撤消。"`	`"此操作不可逆。"`
`"hold shift to drag in files"`	`"按住shift拖动文件"`	`"Shift+拖拽文件"`
`"Double click to edit"`	`"双击进行编辑"`	`"双击编辑"`

Common Pitfalls

Avoid overly literal translations that sound awkward
- ✗ "Do more with Boomerang Tasks" → "使用回旋镖任务完成更多工作"
- ✓ "Do more with Boomerang Tasks" → "允许任务拆分"
Keep feature descriptions accurate
- ✗ "Enhance prompt with additional context" → "使用附加上下文增强提示"
- ✓ "Enhance prompt with additional context" → "增强提示词"
Clear operating guidance
- ✗ "hold shift to drag in files" → "按住shift拖动文件"
- ✓ "hold shift to drag in files" → "Shift+拖拽文件"
Ensure terminology consistency
- ✗ Mixing "Token"/"令牌"/"代币" in the same document
- ✓ Consistently use "Token" as the technical term
Pay attention to cultural adaptability
- ✗ "Kill the process" → "杀死进程"(too violent)
- ✓ "Kill the process" → "终止进程"
Special handling for technical documentation
- Comments in code examples: ✗ Translation breaks the code structure ✓ Keep code comments as-is or translate only the explanatory part
- Command-line parameters: ✗ Translating parameter names makes them unusable ✓ Keep parameter names in English and translate only the descriptions

Best Practices

Translation Workflow
- Read the full text to understand the context
- Mark and unify technical terminology
- Translate in segments and check consistency
- Final overall review
Key Quality Checkpoints
- Terminology consistency
- Accuracy of feature descriptions
- Suitability of UI element lengths
- Cultural Adaptability
Tool Usage Recommendations
- Establish a project terminology base
- Use translation memory tools
- Maintain a style guide
- Regularly update translation resources
Review Process
- Initial translation → Technical review → Language polishing → Final confirmation
- Focus on technical accuracy, language fluency, and UI display effect

Quality Checklist

Are terms consistent throughout the text?
Does it conform to Chinese technical documentation conventions?
Is the UI control text concise and clear?
Have long sentences been reasonably split?
Are variable placeholders kept in their original format?
Are technical descriptions accurate and error-free?
Are cultural expressions appropriate?
Has the precise meaning of the original text been preserved?
Are special formats (such as variables and code) correctly preserved?

Traditional Chinese (zh-TW) Translation Guidelines

Key Terminology

English Term	Use (zh-TW)	Avoid (Mainland)
file	檔案	文件
task	工作	任務
project	專案	項目
configuration	設定	配置
server	伺服器	服務器
import/export	匯入/匯出	導入/導出

Formatting Rules

Add spaces between Chinese and English/numbers: "AI 驅動" (not "AI驅動")
Use Traditional Chinese quotation marks: 「範例文字」(not "範例文字")
Use Taiwanese computing conventions rather than mainland terminology

About this skill

German (de) Translation Guidelines

Quick Reference

Simplified Chinese (zh-CN) Translation Guidelines

Key Terminology

Formatting Rules

UI Element Translation Standards

Contextual Translation Principles

Technical Documentation Guidelines

Common Patterns

Common Pitfalls

Best Practices

Quality Checklist

Traditional Chinese (zh-TW) Translation Guidelines

Key Terminology

Formatting Rules