Language Conventions

Language Conventions

Instructions

Core rule

{{USER_LANG}}: User communication, documentation, commits English: Code, comments, technical identifiers

Quick reference

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