SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillstranslation

translation

Writing & research

View repository

Updated 10-15 23:46

About this skill

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

  1. 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}}"

  2. Punctuation

    • Use Chinese full-width punctuation
    • Use Chinese enumeration comma for list items: "创建、编辑文件"

  3. 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: "展开" is better than "查看更多"

  4. Technical descriptions

    • Keep English abbreviations: e.g., do not translate "MCP"
    • 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: "计算机交互" is better than "计算机使用"
    • Parameter description: "差异更新" is better than "差分/补丁"

  5. Variable placeholders

    • Keep the original format:{{variable}}
    • Place Chinese descriptions outside the variable: "Token 使用量: {{used}}"

UI Element Translation Standards

  1. Buttons

    • Confirmation type: OK/Cancel/Apply/Save
    • Action type: Add/Delete/Edit/Export
    • State type: Enable/Disable/Expand/Collapse
    • Length limit: 2-4 Chinese characters

  2. Menus

    • Main menu: File/Edit/View/Help
    • Submenu: use ">" to connect, e.g., "文件>打开"
    • Shortcuts: keep English, e.g., "Ctrl+S"

  3. Labels

    • Setting items: describe the function, e.g., "自动保存间隔"
    • Status prompts: concise and clear, e.g., "正在处理..."
    • Unit descriptions: place in parentheses, e.g., "超时时间(秒)"

  4. Tooltips

    • Feature description: concise description, e.g., "复制选中内容"
    • Operation guidance: clear steps, e.g., "双击编辑单元格"
    • Length limit: no more than 50 Chinese characters

  5. Dialogs

    • Title: explain the purpose of the dialog
    • Body: explain in paragraphs
    • Buttons: use verbs, e.g., "确认删除"

Contextual Translation Principles

  1. Adjust according to UI position

    • Button text: concise verb (e.g., "展开", "收起")
    • Setting items: descriptive (e.g., "自动批准写入操作")
    • Help text: complete explanation (e.g., "开启后自动创建任务存档点，方便回溯修改")

  2. Technical documentation style

    • Use active voice: e.g., "自动创建和编辑文件"
    • Avoid colloquial expressions
    • Use bullet points for complex features
    • Explain the operation result: e.g., "无需二次确认"
    • Clear parameter descriptions: e.g., "延迟一段时间再自动批准写入"

  3. Brand/Product names

    • Keep English brand names
    • Keep technical terminology consistent
    • Keep English proper nouns: e.g., "Amazon Bedrock ARN"

  4. User operations

    • Unify action verbs:
      • "Click" → "点击"
      • "Type" → "输入"
      • "Scroll" → "滚动"
    • Button states:
      • "Enabled" → "已启用"
      • "Disabled" → "已禁用"

Technical Documentation Guidelines

  1. Technical terminology

    • Use "Token" consistently instead of "令牌"
    • Keep English proper nouns: e.g., "Model Context Protocol"
    • Unified feature naming: e.g., "computer function calling" is better than "computer use"

  2. API Documentation

    • Endpoint: keep the original path
    • Parameter descriptions: present in table form
    • Examples: keep the code format
    • Parameter labels:
      • Clear units: e.g., "maximum output Token count"
      • Complete range description: e.g., "the total number of Tokens the model can process"

  3. Code-related translation

    • Code comments:
      • Keep technical terms: e.g., "// Initialize MCP client"
      • Brief description: e.g., "check whether the file exists"
    • Error messages:
      • Include error codes: e.g., "Error 404: file not found"
      • Provide solutions: e.g., "please check file permissions"
    • Command line:
      • Keep native commands: e.g., "git commit -m 'message'"
      • Parameter descriptions: e.g., "-v: show detailed output"

  4. Configuration Guide

    • Setting item naming: e.g., "Enable prompt caching" → "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"
    • Operation 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

  1. Avoid overly literal translations that sound stiff

    • ✗ "Do more with Boomerang Tasks" → "Use boomerang tasks to get more work done"
    • ✓ "Do more with Boomerang Tasks" → "Allow task splitting"

  2. Keep feature descriptions accurate

    • ✗ "Enhance prompt with additional context" → "Use additional context to enhance the prompt"
    • ✓ "Enhance prompt with additional context" → "Enhance prompt"

  3. Clear operation guidance

    • ✗ "hold shift to drag in files" → "Hold shift to drag files"
    • ✓ "hold shift to drag in files" → "Shift+drag files"

  4. Ensure terminology consistency

    • ✗ Mixing "Token"/"token"/"coin" in the same document
    • ✓ Consistently use "Token" as the technical term

  5. Pay attention to cultural adaptability

    • ✗ "Kill the process" → "Kill the process" (too violent)
    • ✓ "Kill the process" → "Terminate the process"

  6. 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

  1. Translation workflow

    • Read the full text to understand the context
    • Mark and unify technical terms
    • Translate in sections and check consistency
    • Final overall review

  2. Quality check points

    • Terminology consistency
    • Accuracy of feature descriptions
    • UI element length adaptability
    • Cultural Adaptability

  3. Tool Usage Recommendations

    • Establish a project terminology base
    • Use translation memory tools
    • Maintain a style guide
    • Regularly update translation resources

  4. Review Process

    • Initial translation → Technical review → Language polishing → Final confirmation
    • Focus on technical accuracy, language fluency, and UI display effects

Quality Checklist

  1. Are terms consistent throughout the text?
  2. Does it conform to Chinese technical documentation conventions?
  3. Is the UI control text concise and clear?
  4. Have long sentences been reasonably split?
  5. Are variable placeholders kept in their original format?
  6. Is the technical description accurate and error-free?
  7. Is the cultural expression appropriate?
  8. Has the precise meaning of the original text been preserved?
  9. 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