Problem Description
In the setup wizard (step 4/10), the Chinese translation uses the term “宪法” (constitution) for the user-defined rules/guidelines, and “代码” (code) for both the delivered software and the internal assistant persona “CodeWhale”. This causes serious confusion for native Chinese speakers:
- “宪法” is perceived as a national legal document, which feels overly heavy and out of place in a coding assistant context.
- The dual use of “代码” (one for software source code, the other for the assistant’s identity) is ambiguous – users cannot intuitively tell which “code” is being referred to.
- The wizard text mixes metaphoric expressions (e.g., “起草你的宪法”, “教义模块”, “自由原则”) that are literally translated, resulting in a stiff, bureaucratic tone rather than a friendly, technical one.
Many Chinese users would struggle to understand that this step is simply about setting personal preferences or a rulebook for the assistant’s behavior. The translation feels like a direct word‑for‑word mapping from English, without adapting to Chinese semantics and user expectations.
Why This Happens – Cultural & Linguistic Gap
| English term |
Literal Chinese |
Actual perceived meaning in Chinese |
Suggested alternative |
| Constitution |
宪法 |
National supreme law – too authoritative and formal |
准则 / 约定 / 行为规范 (guidelines / convention / code of conduct) |
| Code (software) |
代码 |
Source code – clear and unambiguous |
Keep as 代码 |
| Code (assistant) |
代码 |
Same as above – leads to confusion |
助手 / 智能体 (assistant / agent) or keep “CodeWhale” untranslated |
| Doctrine modules |
教义模块 |
Religious or political dogma – inappropriate |
规则包 / 可选策略 (rule packs / optional policies) |
| Freedom principle |
自由原则 |
Political freedom – overly broad |
自定义原则 / 灵活规则 (custom principles / flexible rules) |
Core difference: English favors analogical/metaphorical naming – using familiar, evocative terms (e.g., “constitution” for a set of rules, “doctrine” for a collection of policies) to create a strong mental image. Chinese, however, prefers explicit, concrete, and functional naming – users expect to see exactly what a thing does, not what it resembles. When metaphors are translated literally, they lose their poetic appeal and become either comical or misleading.
For a developer tool, clarity and ease of understanding are paramount. A Chinese user scanning the wizard should immediately grasp that they are defining personal preferences or a rulebook, not drafting a national law.
Suggestions for Future Translation Work
Since the developer is likely non‑Chinese and using AI‑assisted translation, I recommend the following practical steps:
-
Avoid literal metaphors – Translate the purpose, not the English word. For example, “constitution” → “行为准则” (code of conduct) or “用户约定” (user agreement). “Doctrine” → “预设策略组” (preset policy groups).
-
Distinguish homonyms clearly – Keep “CodeWhale” as the proper noun (untranslated) or call it “鲸鱼助手” (Whale Assistant) to separate it from source code.
-
Use glossary consistency – Provide a Chinese terminology table to the translator (or AI prompt) that maps each key English term to a single, context‑appropriate Chinese phrase, with examples in sentences.
-
Add a context note for the translator – For each UI string, include a short explanation of what the feature does and who the audience is (e.g., “This is a rule set that users can customize; keep it casual and tech‑friendly”).
-
Consider a community review – Before finalizing, publish a draft of the Chinese localization on a public channel (e.g., GitHub Discussion) and invite native speakers to vote/suggest improvements. This is low‑cost and yields high‑quality feedback.
-
Fallback to English – If a term is too culturally bound (e.g., “constitution”), keep the English word and add a brief Chinese explanation in parentheses, until a better native term emerges.
I’m happy to help review future translations if needed. Thank you for your great work on this tool – a polished i18n will significantly improve the experience for Chinese developers.
Problem Description
In the setup wizard (step 4/10), the Chinese translation uses the term “宪法” (constitution) for the user-defined rules/guidelines, and “代码” (code) for both the delivered software and the internal assistant persona “CodeWhale”. This causes serious confusion for native Chinese speakers:
Many Chinese users would struggle to understand that this step is simply about setting personal preferences or a rulebook for the assistant’s behavior. The translation feels like a direct word‑for‑word mapping from English, without adapting to Chinese semantics and user expectations.
Why This Happens – Cultural & Linguistic Gap
Core difference: English favors analogical/metaphorical naming – using familiar, evocative terms (e.g., “constitution” for a set of rules, “doctrine” for a collection of policies) to create a strong mental image. Chinese, however, prefers explicit, concrete, and functional naming – users expect to see exactly what a thing does, not what it resembles. When metaphors are translated literally, they lose their poetic appeal and become either comical or misleading.
For a developer tool, clarity and ease of understanding are paramount. A Chinese user scanning the wizard should immediately grasp that they are defining personal preferences or a rulebook, not drafting a national law.
Suggestions for Future Translation Work
Since the developer is likely non‑Chinese and using AI‑assisted translation, I recommend the following practical steps:
Avoid literal metaphors – Translate the purpose, not the English word. For example, “constitution” → “行为准则” (code of conduct) or “用户约定” (user agreement). “Doctrine” → “预设策略组” (preset policy groups).
Distinguish homonyms clearly – Keep “CodeWhale” as the proper noun (untranslated) or call it “鲸鱼助手” (Whale Assistant) to separate it from source code.
Use glossary consistency – Provide a Chinese terminology table to the translator (or AI prompt) that maps each key English term to a single, context‑appropriate Chinese phrase, with examples in sentences.
Add a context note for the translator – For each UI string, include a short explanation of what the feature does and who the audience is (e.g., “This is a rule set that users can customize; keep it casual and tech‑friendly”).
Consider a community review – Before finalizing, publish a draft of the Chinese localization on a public channel (e.g., GitHub Discussion) and invite native speakers to vote/suggest improvements. This is low‑cost and yields high‑quality feedback.
Fallback to English – If a term is too culturally bound (e.g., “constitution”), keep the English word and add a brief Chinese explanation in parentheses, until a better native term emerges.
I’m happy to help review future translations if needed. Thank you for your great work on this tool – a polished i18n will significantly improve the experience for Chinese developers.