Contributing & Bug Reports

LangSwitcher is a free, open-source project under the MIT License. Contributions of any kind are welcome!

Reporting Bugs

Found a bug? Please open an issue on GitHub.

What to include in a bug report

1. Description — what happened vs. what you expected
2. Steps to reproduce — how to trigger the bug
3. macOS version — e.g., macOS 15.2 Sequoia
4. LangSwitcher version — shown in Settings → About
5. Keyboard layouts — which layouts you have enabled
6. Conversion log — export from Settings → Log → Export JSON and attach the file

Example bug report

**Bug:** Text not converting correctly for German layout

**Steps:**
1. Enable German (QWERTZ) and English (QWERTY) layouts
2. Type "hallo" while in English layout (produces "hallo")
3. Press ⇧⇧
4. Expected: "hallo" (correct German) — Actual: "jzllo"

**macOS:** 15.2
**LangSwitcher:** 1.0.0
**Layouts:** U.S., German

**Log attached:** conversion-log-2026-03-01.json

Feature Requests

Have an idea for a new feature? Open an issue with the enhancement label. Describe:

• What you want to achieve
• Why it would be useful
• Any implementation ideas you have

Contributing Code

Getting Started

1. Fork the repository
2. Clone your fork
3. Open LangSwitcher.xcodeproj in Xcode
4. Make your changes
5. Run tests:

xcodebuild test \
  -project LangSwitcher.xcodeproj \
  -scheme LangSwitcher \
  -destination 'platform=macOS' \
  CODE_SIGN_IDENTITY="-" \
  CODE_SIGNING_REQUIRED=NO \
  CODE_SIGNING_ALLOWED=NO

6. Commit and push
7. Open a Pull Request

Guidelines

• All tests must pass before submitting a PR
• New features require tests — add unit tests for any new functionality
• Follow the existing code style — pure Swift, no external dependencies
• Localization — all new UI strings must go through LocalizationManager.shared.t("key") and be added to both Strings_en.swift and Strings_ru.swift

Adding a New Layout

1. Create a new LayoutCharacterMap in Sources/Services/LayoutMapper.swift
2. Add the character mapping between the new layout and English
3. Register the map in allMaps
4. Add tests in LangSwitcherTests/LayoutMapperTests.swift
5. Update documentation (this docs site)

Community

• GitHub Issues — bug reports and feature requests
• GitHub Discussions — general questions and ideas
• Pull Requests — code contributions

Thank you for helping make LangSwitcher better!