language-conventions
Defines language usage conventions separating user communication from technical artifacts. Use when writing code, documentation, commits, or communicating with users in multilingual projects.
When & Why to Use This Skill
The Language Conventions skill optimizes multilingual software development by enforcing a strict separation between technical artifacts and user communication. It ensures that code, comments, and identifiers adhere to international English standards, while documentation, commit messages, and user interactions are localized to the team's preferred language, enhancing both global compatibility and local clarity.
Use Cases
- Standardizing multilingual codebases: Maintain English for all code and technical identifiers while using a local language for documentation and team communication.
- Localizing developer workflows: Automatically generate commit messages and pull request descriptions in a specific user language without compromising English-only code standards.
- Improving team collaboration: Facilitate better understanding among non-native English speaking teams by allowing technical discussions and documentation in their primary language.
- Globalizing open-source contributions: Ensure that code remains accessible to the international community while providing localized context for local contributors.
| name | language-conventions |
|---|---|
| description | Defines language usage conventions separating user communication from technical artifacts. Use when writing code, documentation, commits, or communicating with users in multilingual projects. |
Language Conventions
Instructions
Core rule
{{USER_LANG}}: User communication, documentation, commits English: Code, comments, technical identifiers
Quick reference
| Artifact | Language | Why |
|---|---|---|
| User messages | {{USER_LANG}} | User's language |
| Code | English | International standard |
| Comments | English | Matches code |
| Variables/Functions | English | Part of code |
| Commits | {{USER_LANG}} | Team communication |
| Documentation | {{USER_LANG}} | User's language |
| Tags | English | Technical ID |
Example
# User: {{USER_LANG}}
"{{User message in local language}}"
# Code: English
# @FEAT:{{feature-name}} @COMP:service @TYPE:core
class {{EntityName}}ValidationService:
'''Validates {{entities}} before submission'''
def validate(self, {{entity}}: dict) -> bool:
# Validate {{field}} is positive
if {{entity}}.get('{{field}}', 0) <= 0:
return False
return True
# User: {{USER_LANG}}
"{{Completion message in local language}}"
Common mistakes
# ❌ {{USER_LANG}} in code
def {{local_language_function_name}}({{local_language_param}}): pass
# ❌ English to user
"Implementation complete."
# ✅ Correct
"{{Completion message in user language}}"
def {{english_function_name}}({{english_param}}): pass
Multi-Language Examples
Python
# User communication: {{USER_LANG}}
# Code: English
# @FEAT:user-auth @COMP:service @TYPE:core
class AuthenticationService:
'''Handles user authentication'''
def authenticate(self, username: str, password: str) -> bool:
# Validate credentials
if not username or not password:
return False
return True
JavaScript/TypeScript
// User communication: {{USER_LANG}}
// Code: English
// @FEAT:user-auth @COMP:service @TYPE:core
class AuthenticationService {
/**
* Handles user authentication
*/
authenticate(username, password) {
// Validate credentials
if (!username || !password) {
return false;
}
return true;
}
}
Go
// User communication: {{USER_LANG}}
// Code: English
// @FEAT:user-auth @COMP:service @TYPE:core
// AuthenticationService handles user authentication
type AuthenticationService struct{}
// Authenticate validates user credentials
func (s *AuthenticationService) Authenticate(username, password string) bool {
// Validate credentials
if username == "" || password == "" {
return false
}
return true
}
Language-Agnostic Alternative
If your project uses English for all communication:
### Simplified Single-Language Policy
**English everywhere:** User communication, code, documentation, commits
| Artifact | Language |
|----------|----------|
| User messages | English |
| Code | English |
| Comments | English |
| Variables/Functions | English |
| Commits | English |
| Documentation | English |
| Tags | English |
**Consistency:** Use clear, professional English throughout all artifacts.
For detailed guidelines, see reference.md For more examples, see examples.md