baijum/add-translations

Add Translations

Add new string and plural resources to all supported locales for Android (strings.xml) and iOS (Localizable.xcstrings).

Android strings.xml files are the source of truth for translations. The converter script scripts/convert_strings.py generates the iOS Localizable.xcstrings from Android sources.

Supported Locales

| Code | Language | Android path | iOS | |------|----------|-------------|-----| | en | English (source) | app/src/main/res/values/strings.xml | Localizable.xcstrings (sourceLanguage) | | ar | Arabic | values-ar/strings.xml | Localizable.xcstrings → ar | | zh-Hans | Chinese (Simplified) | values-b+zh+Hans/strings.xml | Localizable.xcstrings → zh-Hans | | de | German | values-de/strings.xml | Localizable.xcstrings → de | | es | Spanish | values-es/strings.xml | Localizable.xcstrings → es | | fr | French | values-fr/strings.xml | Localizable.xcstrings → fr | | hi | Hindi | values-hi/strings.xml | Localizable.xcstrings → hi | | in | Indonesian | values-in/strings.xml | Localizable.xcstrings → id | | it | Italian | values-it/strings.xml | Localizable.xcstrings → it | | ja | Japanese | values-ja/strings.xml | Localizable.xcstrings → ja | | ko | Korean | values-ko/strings.xml | Localizable.xcstrings → ko | | nl | Dutch | values-nl/strings.xml | Localizable.xcstrings → nl | | pl | Polish | values-pl/strings.xml | Localizable.xcstrings → pl | | pt | Portuguese | values-pt/strings.xml | Localizable.xcstrings → pt | | ru | Russian | values-ru/strings.xml | Localizable.xcstrings → ru | | tr | Turkish | values-tr/strings.xml | Localizable.xcstrings → tr |

All Android paths are relative to app/src/main/res/.

Workflow

Step 1: Identify strings to translate

Common triggers:

• Adding new UI text (buttons, labels, accessibility descriptions)
• MissingTranslation lint errors from ./gradlew lintDebug
• New strings added to values/strings.xml without locale counterparts

To find missing strings, run:

./gradlew lintDebug 2>&1 | grep "MissingTranslation"

Step 2: Add to English source (if not already present)

Android: Add <string name="key">English text</string> to app/src/main/res/values/strings.xml, grouped with related strings.

For quantity-dependent text, use <plurals> instead:

<plurals name="key">
    <item quantity="one">%1$d item</item>
    <item quantity="other">%1$d items</item>
</plurals>

Valid quantity values: zero, one, two, few, many, other. Most languages need only one and other. Arabic needs all six; Russian/Polish need one, few, many, other.

Step 3: Add translations to all 15 locale files

Android: For each locale strings.xml, add a <string name="key">Translated text</string> entry before </resources>. For plurals, add a <plurals name="key"> block with the appropriate <item quantity="..."> entries for each locale.

Use a subagent (model: fast) to update all 15 files in parallel when adding multiple strings. Provide the subagent with:

1. The exact string key(s)
2. The translated text for each locale
3. An anchor string near the insertion point (a unique existing <string> near the end of each file)

Example subagent prompt pattern:

Add these strings to all 15 locale strings.xml files in
app/src/main/res/. Find the anchor string "existing_key" near
the end of each file and add the new strings after it, before
</resources>.

Translations:
- values-ar: <string name="my_key">Arabic text</string>
- values-de: <string name="my_key">German text</string>
...

Step 4: Generate iOS string catalog

Run the converter script to regenerate Localizable.xcstrings from Android sources:

python3 scripts/convert_strings.py

This handles both <string> and <plurals> elements across all locales. Do NOT edit Localizable.xcstrings manually.

Step 5: Verify

./gradlew lintDebug

Lint must pass with 0 errors. Warnings are acceptable.

Translation Guidelines

• Keep translations concise — UI space is limited, especially on mobile
• Preserve format specifiers exactly: %1$d, %s, %1$@, %lld, etc.
• Preserve XML entities: &, <, \', etc.
• Do not translate brand names (e.g., "ChordPro", "Ukulele Companion")
• Accessibility strings (cd_* prefix) should be natural spoken language
• For technical terms with no good translation, keep the English term (e.g., "PDF", "BPM")

Format Specifier Mapping (Android ↔ iOS)

| Android | iOS | Type | |---------|-----|------| | %d, %1$d | %lld, %1$lld | Integer | | %s, %1$s | %@, %1$@ | String | | %f, %1$f | %f, %1$f | Float | | %% | %% | Literal percent |

Quick Reference

| Task | Command | |------|---------| | Check missing translations | ./gradlew lintDebug 2>&1 \| grep MissingTranslation | | Run full lint | ./gradlew lintDebug | | Generate iOS string catalog | python3 scripts/convert_strings.py | | List all string keys | grep 'name="' app/src/main/res/values/strings.xml | | Count keys per locale | grep -c '<string' app/src/main/res/values-de/strings.xml |