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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

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.
namelanguage-conventions
descriptionDefines 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