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 .novacode/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="#" />
    }}
  />

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

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

Simplified Chinese (zh-CN) Translation Guidelines

Key Terminology

Formatting Rules

1. 中英文混排

   • 添加空格：在中文和英文/数字之间添加空格，如"API 费用"（不是"API费用"）
   • 单位格式：时间单位统一为"15秒"、"1分钟"（不是"15 seconds"、"1 minute"）
   • 数字范围："已使用: {{used}} / {{total}}"
   • 技术符号保留原样："{{amount}} tokens"→"{{amount}}"

2. 标点符号

   • 使用中文全角标点
   • 列表项使用中文顿号："创建、编辑文件"

3. UI文本优化

   • 按钮文本：使用简洁动词，如"展开"优于"查看更多"
   • 操作说明：使用步骤式说明（1. 2. 3.）替代长段落
   • 错误提示：使用"确认删除？此操作不可逆"替代"Are you sure...?"
   • 操作说明要简洁："Shift+拖拽文件"优于长描述
   • 按钮文本控制在2-4个汉字："展开"优于"查看更多"

4. 技术描述

   • 保留英文缩写：如"MCP"不翻译
   • 统一术语：整个系统中相同概念使用相同译法
   • 长句拆分为短句
   • 被动语态转为主动语态
   • 功能名称统一："计算机交互"优于"计算机使用"
   • 参数说明："差异更新"优于"差分/补丁"

5. 变量占位符

   • 保持原格式：{{variable}}
   • 中文说明放在变量外："Token 使用量: {{used}}"

UI Element Translation Standards

1. 按钮(Buttons)

   • 确认类：确定/取消/应用/保存
   • 操作类：添加/删除/编辑/导出
   • 状态类：启用/禁用/展开/收起
   • 长度限制：2-4个汉字

2. 菜单(Menus)

   • 主菜单：文件/编辑/视图/帮助
   • 子菜单：使用">"连接，如"文件>打开"
   • 快捷键：保留英文，如"Ctrl+S"

3. 标签(Labels)

   • 设置项：描述功能，如"自动保存间隔"
   • 状态提示：简洁明确，如"正在处理..."
   • 单位说明：放在括号内，如"超时时间(秒)"

4. 工具提示(Tooltips)

   • 功能说明：简洁描述，如"复制选中内容"
   • 操作指引：步骤明确，如"双击编辑单元格"
   • 长度限制：不超过50个汉字

5. 对话框(Dialogs)

   • 标题：说明对话框用途
   • 正文：分段落说明
   • 按钮：使用动词，如"确认删除"

Contextual Translation Principles

1. 根据UI位置调整

   • 按钮文本：简洁动词 (如"展开", "收起")
   • 设置项：描述性 (如"自动批准写入操作")
   • 帮助文本：完整说明 (如"开启后自动创建任务存档点，方便回溯修改")

2. 技术文档风格

   • 使用主动语态：如"自动创建和编辑文件"
   • 避免口语化表达
   • 复杂功能使用分点说明
   • 说明操作结果：如"无需二次确认"
   • 参数说明清晰：如"延迟一段时间再自动批准写入"

3. 品牌/产品名称

   • 保留英文品牌名
   • 技术术语保持一致性
   • 保留英文专有名词：如"Amazon Bedrock ARN"

4. 用户操作

   • 操作动词统一：
     • "Click"→"点击"
     • "Type"→"输入"
     • "Scroll"→"滚动"
   • 按钮状态：
     • "Enabled"→"已启用"
     • "Disabled"→"已禁用"

Technical Documentation Guidelines

1. 技术术语

   • 统一使用"Token"而非"令牌"
   • 保留英文专有名词：如"Model Context Protocol"
   • 功能名称统一：如"计算机功能调用"优于"计算机使用"

2. API文档

   • 端点(Endpoint)：保留原始路径
   • 参数说明：表格形式展示
   • 示例：保留代码格式
   • 参数标签：
     • 单位明确：如"最大输出 Token 数"
     • 范围说明完整：如"模型可以处理的总 Token 数"

3. 代码相关翻译

   • 代码注释：
     • 保留技术术语：如"// Initialize MCP client"
     • 简短说明：如"检查文件是否存在"
   • 错误信息：
     • 包含错误代码：如"Error 404: 文件未找到"
     • 提供解决方案：如"请检查文件权限"
   • 命令行：
     • 保留原生命令：如"git commit -m 'message'"
     • 参数说明：如"-v: 显示详细输出"

4. 配置指南

   • 设置项命名：如"Enable prompt caching"→"启用提示词缓存"
   • 价格描述：
     • 单位统一：如"每百万 Token 的成本"
     • 说明影响：如"这会影响生成内容和补全的成本"
   • 操作说明：
     • 使用编号步骤：如"1. 注册Google Cloud账号"
     • 步骤动词一致：如"安装配置Google Cloud CLI工具"

Common Patterns

Common Pitfalls

1. 避免过度直译导致生硬

   • ✗ "Do more with Boomerang Tasks" → "使用回旋镖任务完成更多工作"
   • ✓ "Do more with Boomerang Tasks" → "允许任务拆分"

2. 保持功能描述准确

   • ✗ "Enhance prompt with additional context" → "使用附加上下文增强提示"
   • ✓ "Enhance prompt with additional context" → "增强提示词"

3. 操作指引清晰

   • ✗ "hold shift to drag in files" → "按住shift拖动文件"
   • ✓ "hold shift to drag in files" → "Shift+拖拽文件"

4. 确保术语一致性

   • ✗ 同一文档中混用"Token"/"令牌"/"代币"
   • ✓ 统一使用"Token"作为技术术语

5. 注意文化适应性

   • ✗ "Kill the process" → "杀死进程"(过于暴力)
   • ✓ "Kill the process" → "终止进程"

6. 技术文档特殊处理

   • 代码示例中的注释： ✗ 翻译后破坏代码结构 ✓ 保持代码注释原样或仅翻译说明部分
   • 命令行参数： ✗ 翻译参数名称导致无法使用 ✓ 保持参数名称英文，仅翻译说明

Best Practices

1. 翻译工作流程

   • 通读全文理解上下文
   • 标记并统一技术术语
   • 分段翻译并检查一致性
   • 最终整体审校

2. 质量检查要点

   • 术语一致性
   • 功能描述准确性
   • UI元素长度适配性
   • 文化适应性

3. 工具使用建议

   • 建立项目术语库
   • 使用翻译记忆工具
   • 维护风格指南
   • 定期更新翻译资源

4. 审校流程

   • 初翻 → 技术审校 → 语言润色 → 最终确认
   • 重点关注技术准确性、语言流畅度和UI显示效果

Quality Checklist

1. 术语是否全文一致？
2. 是否符合中文技术文档习惯？
3. UI控件文本是否简洁明确？
4. 长句是否已合理拆分？
5. 变量占位符是否保留原格式？
6. 技术描述是否准确无误？
7. 文化表达是否恰当？
8. 是否保持了原文的精确含义？
9. 特殊格式(如变量、代码)是否正确保留？

Traditional Chinese (zh-TW) Translation Guidelines

Key Terminology

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

Source: DerstedtCasper/vcp-code-2.0 — distributed by TomeVault.