Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
176 lines (127 loc) · 4.66 KB

CONTRIBUTING.md

File metadata and controls

176 lines (127 loc) · 4.66 KB
Raw

Contributing to MicYou

Thank you for your interest in contributing to MicYou! This guide covers how to build the app from source, add translations, and submit changes.

We welcome bug reports, feature requests, code contributions, and translations.

Building from Source

This project is built using Kotlin Multiplatform.

Android app (APK):

./gradlew :composeApp:assembleDebug

Desktop application (run directly):

./gradlew :composeApp:run

Build packages for distribution:

Windows installer (NSIS):

./gradlew :composeApp:packageWindowsNsis

Windows ZIP archive:

./gradlew :composeApp:packageWindowsZip

Linux DEB package:

./gradlew :composeApp:packageDeb

Linux RPM package:

./gradlew :composeApp:packageRpm

macOS DMG package:

./gradlew :composeApp:packageDmg

No-JRE package:

./gradlew :composeApp:packageNoJreAll

Internationalization (i18n)

MicYou uses Compose Multiplatform Resources for localization. All user-facing strings are stored in strings.xml files. We welcome contributions to translate MicYou into your language!

Adding a New Language

To add a new language manually:

  1. Clone the repository:
git clone https://github.com/LanRhyme/MicYou.git
cd MicYou
  1. Create a new strings.xml file under the appropriate values-{locale} directory:
mkdir -p composeApp/src/commonMain/composeResources/values-xx
cp composeApp/src/commonMain/composeResources/values/strings.xml composeApp/src/commonMain/composeResources/values-xx/strings.xml

Replace xx with your language code (e.g., fr for French, es for Spanish, according to ISO 639-1 or other related standards like IETF BCP 47).

  1. Edit the new strings.xml file and translate all string values while keeping the keys unchanged:
<resources>
    <string name="appName">MicYou</string>
    <string name="ipLabel">IP : </string>
    <!-- ... -->
</resources>
  1. Register the new language in Localization.kt:

Find the AppLanguage enum and add your language:

enum class AppLanguage(val label: String, val code: String) {
    // ... existing languages ...
    French("Français", "fr"),  // Add this line
}

Using Strings in Code

// In @Composable context
Text(stringResource(Res.string.myKey))

// In suspend context
val text = getString(Res.string.myKey)

// With format args (%s, %d, %1$s for positional)
Text(stringResource(Res.string.myFormattedKey, arg1))

Testing Translations

To test your translation locally:

  1. Build and run the desktop app:
./gradlew :composeApp:run

  1. Go to Settings → Appearance → Language and select your new language

  2. Check that all strings display correct text and that layouts don't clip or overflow

  3. For Android app, build APK:

./gradlew :composeApp:assembleDebug

Translation Workflow

  • Base languages (must be kept in sync): English (values/strings.xml) and Simplified Chinese (values-zh/strings.xml)
  • Location: composeApp/src/commonMain/composeResources/values*/strings.xml
  • File format: Android strings.xml
  • Currently supported: 6 locales including Chinese (Simplified, Traditional, Cantonese)

Translation Update Process (GitHub workflow)

When you add or update translations, follow this order:

  1. Update both base language files first:
composeApp/src/commonMain/composeResources/values/strings.xml      (English)
composeApp/src/commonMain/composeResources/values-zh/strings.xml   (Simplified Chinese)

  1. Update other locale files (values-*/strings.xml) using the same key set.

  2. Run localization checks locally:

./gradlew checkLocalization
  1. Install hooks once (recommended) so checks run automatically before each commit:
./gradlew installGitHooks
  1. Commit changes only after checkLocalization passes.

The pre-commit hook runs checkLocalization and blocks commits when key sets are inconsistent or values are empty.

Special Language Variants

Some languages have special variants:

  • values-zh/ - Simplified Chinese
  • values-zh-rTW/ - Traditional Chinese (Taiwan)
  • values-zh-rHK/ - Cantonese (Hong Kong)
  • values-zh-rSS/ - Chinese Hard mode (Easter egg)
  • values-ca/ - Cat language (Easter egg)

Contributing Translations

Submit a pull request with your new or updated translation files.

Submitting Changes

Use Conventional Commits format for all PR titles:

  • feat(i18n): add fr (French) localization
  • fix: resolve audio crash on Android 14
  • docs: update build instructions