ADR-012: English Language Requirement for Code and Documentation
Status: Accepted
Date: 2025-07-16
Authors: Piotr Brzozowski
Reviewers: Piotr Brzozowski
English is adopted as the mandatory language for all code, comments, documentation, commit messages, and technical communication in the Entirius project. This ensures global accessibility, consistent communication standards, and alignment with open-source industry practices.
- Code: All variable names, function names, class names in English
- Comments: All inline comments and docstrings in English
- Documentation: All technical documentation, README files, API docs in English
- Commit messages: All git commit messages in English using conventional commit format
- Issues & PRs: All GitHub issues and pull request descriptions in English
- Technical communication: All team technical discussions in English
- All new code uses English naming conventions
- Comments and docstrings written in English
- Documentation updated to English where needed
- Commit messages follow English conventional commit format
- Code review process includes language compliance check
- Industry-standard technical terms and abbreviations (API, HTTP, SQL, etc.)
- Established library and framework terminology
- Domain-specific terminology with clear English definitions
As an open-source project with global ambitions, Entirius needs to establish a clear language policy for all code-related content. This includes source code, comments, documentation, commit messages, and all technical communication. The project aims to build an inclusive, accessible, and maintainable codebase that can be understood by developers worldwide.
Currently, the project has mixed language usage across different components, which creates barriers to:
- Code review and collaboration
- Onboarding new international contributors
- Knowledge sharing and documentation consistency
- Maintaining code quality standards
- Building a global developer community
- Description: Enforce English language for all code, comments, documentation, commit messages, and technical communication
- Pros:
- Universal accessibility for international developers
- Consistency across the entire codebase
- Better tooling support (IDEs, linters, spell checkers)
- Easier code review process
- Industry standard practice for open-source projects
- Cons:
- May create initial barriers for non-English speaking contributors
- Requires translation of existing non-English content
- Impact on system: Requires systematic review and translation of existing content
- Description: Allow multiple languages but maintain English translations for all content
- Pros:
- More inclusive for diverse contributors
- Preserves existing multilingual content
- Cons:
- High maintenance overhead
- Inconsistency between language versions
- Complex workflow for contributors
- Potential for outdated translations
- Impact on system: Significant complexity in documentation and review processes
- Description: Prefer English but allow other languages in specific contexts
- Pros:
- Flexibility for contributors
- Gradual migration path
- Cons:
- Inconsistent codebase
- Unclear guidelines for contributors
- Partial accessibility for international developers
- Impact on system: Continued fragmentation of language usage
Chosen option: English-only for all code-related content
Key decision factors:
- Global accessibility: English is the most widely understood language in the software development industry globally
- Industry standard: Alignment with successful open-source projects and established development practices
- Tooling support: Better IDE integration, spell checking, automated documentation generation, and development tool compatibility
- Maintainability: Single language reduces complexity in code reviews, documentation maintenance, and knowledge transfer
- Risk analysis: Minimal technical risk with standard industry practice, temporary migration effort offset by long-term benefits
- Business impact: Enables broader community participation, attracts international contributors, and supports global adoption
- Compatibility: Aligns with chosen technology stack documentation and community practices