# Locale and Label Resolution **Last Updated:** 2026-07-01 **Purpose:** Guide to internationalization (i18n) and label management in CG Mobile applications. --- ## Overview CG Mobile supports multi-language applications through a centralized locale system. Labels, button text, and messages are defined once per language and referenced by ID throughout the application. **Key Benefits:** - ✅ Single source of truth per language - ✅ Consistent translations across modules - ✅ Easy to add new languages - ✅ Separation of UI structure from display text --- ## How Label Resolution Works ### UI Declaration In your `.userinterface.xml` contracts, reference labels by ID: ```xml ``` **Key Attributes:** - `id="CustomerNameLabelId"` — Unique identifier for this label - `defaultLabel="Customer Name"` — Fallback text if translation is missing ### Locale File Entry In each language's locale file (e.g., `src/Locale/en.locale.xml`): ```xml ``` ### Runtime Resolution When the app runs: 1. **User's language setting** determines which locale file to load (e.g., `en.locale.xml`, `de.locale.xml`) 2. **System looks up label** by `id` in the active locale file 3. **If found:** Display `text` value from locale file 4. **If NOT found:** Display `defaultLabel` value from UI contract (fallback) **Best Practice:** Always provide meaningful `defaultLabel` values so the UI is readable even if translations are missing. --- ## Locale File Structure ### File Locations ``` src/Locale/ ├── en.locale.xml # English translations ├── de.locale.xml # German translations ├── es.locale.xml # Spanish translations ├── fr.locale.xml # French translations ├── it.locale.xml # Italian translations ├── ja.locale.xml # Japanese translations ├── pt.locale.xml # Portuguese translations └── zh.locale.xml # Chinese translations ``` Each file follows the same structure with language-specific text. ### XML Structure ```xml ``` --- ## Important Rules ### ❌ DO NOT MODIFY **Framework Section** — Core framework labels (buttons, dialogs, system messages) - ✅ **Use these labels** by referencing their IDs in your UI - ❌ **Never modify** Framework section content - ❌ **Never add** custom labels to Framework section **Global Section** — Core business domain terms - ✅ **Use these labels** by referencing their IDs in your UI - ❌ **Never modify** Global section content - ❌ **Never add** custom labels to Global section **Why:** Framework and Global sections are maintained by the core platform team. Your changes will be overwritten on framework updates. ### ✅ DO MODIFY **UserInterfaceContracts Section** — Your custom module labels - ✅ **Add new `` sections** for your custom UI contracts - ✅ **Add labels** inside your UserInterface sections - ✅ **Update label text** in your UserInterface sections - ✅ **Organize by UI contract** — one `` per `.userinterface.xml` file --- ## Section Organization ### UserInterface ID Naming The `id` attribute should match your UI contract name: | UI Contract File | UserInterface ID | |------------------|------------------| | `Customer_DetailUI.userinterface.xml` | `Customer_DetailUI` | | `Order_ListUI.userinterface.xml` | `Order_ListUI` | | `Product_DataGridUI.userinterface.xml` | `Product_DataGridUI` | | `MyModule_DashboardUI.userinterface.xml` | `MyModule_DashboardUI` | **Pattern:** `{Module}_{Feature}UI` **Benefits:** - Easy to find labels for a specific screen - Clear mapping between UI contract and locale entries - Prevents label ID collisions between modules --- ## Label ID Naming Conventions ### Pattern: `{ControlName}{Purpose}[Id|LabelId]` **Field Labels:** ```xml ``` **Button Labels:** ```xml ``` **Column Headers (DataGrid):** ```xml ``` **Page Titles:** ```xml ``` **Messages:** ```xml ``` **Best Practices:** - ✅ Use descriptive names: `CustomerNameLabelId` not `Label1` - ✅ Include context: `OrderListTitle` not `Title` - ✅ Suffix with `Id` or `LabelId` for consistency - ❌ Avoid generic names: `FieldLabel`, `ButtonText`, `Message` --- ## Translation Status Values ```xml ``` | Value | Meaning | When to Use | |-------|---------|-------------| | `1` | New/Untranslated | Initial label creation in non-English files | | `6` | Text Changed | English text updated, needs re-translation | | `7` | Translated | Translation complete and verified | **Workflow:** 1. **Add label in English (`en.locale.xml`)** with `translationStatus="7"` 2. **Copy to other language files** with `translationStatus="1"` (marks as untranslated) 3. **Translate text** in each language file 4. **Update to `translationStatus="7"`** after translation complete 5. **If English text changes later:** Set to `translationStatus="6"` in other languages (needs re-check) --- ## Adding Labels for a New UI Screen ### Step 1: Create UI Contract **File:** `src/MyModule/PR/MyModule_CustomerDetail/MyModule_CustomerDetailUI.userinterface.xml` ```xml ``` ### Step 2: Add Labels to English Locale **File:** `src/Locale/en.locale.xml` ```xml ``` ### Step 3: Add to Other Languages **File:** `src/Locale/de.locale.xml` ```xml ``` **File:** `src/Locale/fr.locale.xml` ```xml ``` ### Step 4: Build and Test ```bash # Build workspace sf mdl build # Start simulator and test all languages # 1. Navigate to your screen # 2. Verify labels display correctly # 3. Change app language in settings # 4. Verify translations appear correctly ``` --- ## Adding a New Language **Scenario:** Your app supports English and German. Now you need to add Spanish. ### Step 1: Copy English Locale ```bash cd src/Locale/ cp en.locale.xml es.locale.xml ``` ### Step 2: Update Locale Attributes **File:** `src/Locale/es.locale.xml` Change the opening tag: ```xml ``` **From:** ```xml ``` **To:** ```xml ``` ### Step 3: DO NOT Translate Framework/Global **Framework and Global sections remain in English** (read-only, managed by platform team). ```xml ``` ### Step 4: Translate UserInterfaceContracts Section **Only translate YOUR custom labels in UserInterfaceContracts:** ```xml ``` ### Step 5: Build and Test ```bash sf mdl build # Test Spanish language in simulator ``` --- ## Common Patterns ### Pattern 1: Reusing Framework Labels Many common labels already exist in Framework section. **Use them instead of creating duplicates:** **✅ GOOD - Reuse Framework label:** ```xml ``` **❌ BAD - Creating duplicate:** ```xml ``` **How to find existing Framework labels:** ```bash # Search Framework section for common terms grep -i "save\|cancel\|delete\|back\|next" src/Locale/en.locale.xml | grep "" -A 1000 | head -20 ``` **Common Framework labels to reuse:** - `Yes`, `No`, `Cancel`, `OK` - `SaveContinue`, `CancelBack`, `CancelContinue` - `Search`, `Next`, `Previous` - `Confirmation`, `Warning`, `Error`, `Notification` ### Pattern 2: Grouping Related Labels Organize labels by section within a UserInterface: ```xml ``` **Benefits:** - Easier to review translations - Easier to spot missing labels - Better maintainability ### Pattern 3: Context-Specific Labels Use different label IDs for the same English text when context differs: ```xml ``` **Why:** Different contexts may require different translations in other languages. Keep them separate. --- ## Testing Label Resolution ### Quick Visual Test 1. **Build workspace:** ```bash sf mdl build ``` 2. **Start simulator** and navigate to your screen 3. **Check all labels display correctly:** - ✅ Labels show translated text (not IDs) - ✅ Text makes sense in context - ✅ No placeholder text or IDs visible 4. **Test language switching:** - Change app language in settings - Navigate to your screen - Verify all labels change to new language - Verify translations are accurate ### Automated Label Audit Find UI labels missing from locale: ```bash #!/bin/bash # audit-missing-labels.sh UI_FILE="src/MyModule/PR/MyModule_Detail/MyModule_DetailUI.userinterface.xml" LOCALE_FILE="src/Locale/en.locale.xml" UI_ID="MyModule_DetailUI" # Extract all label IDs from UI contract grep -oh 'id="[^"]*"' "$UI_FILE" | \ grep -i "labelid\|headerid\|titleid\|buttonid\|messageid" | \ sed 's/id="//;s/"//' | \ sort -u > ui-labels.txt # Extract all label IDs from this UserInterface section sed -n "//,/<\/UserInterface>/p" "$LOCALE_FILE" | \ grep -oh 'id="[^"]*"' | \ sed 's/id="//;s/"//' | \ sort -u > locale-labels.txt # Find missing labels (in UI but not in locale) comm -23 ui-labels.txt locale-labels.txt > missing-labels.txt if [ -s missing-labels.txt ]; then echo "⚠️ Missing labels in locale file for $UI_ID:" cat missing-labels.txt else echo "✅ All UI labels exist in locale file" fi # Cleanup rm ui-labels.txt locale-labels.txt missing-labels.txt ``` --- ## Best Practices ### 1. One UserInterface Section Per UI Contract **✅ DO:** ```xml ``` **❌ DON'T:** ```xml ``` ### 2. Meaningful Default Labels Always provide clear `defaultLabel` values: **✅ GOOD:** ```xml ``` **❌ BAD:** ```xml ``` **Why:** If translation is missing, users see the defaultLabel. Make it useful. ### 3. Check Framework Before Creating Before adding a label to UserInterfaceContracts, check if it exists in Framework: ```bash # Search for common button labels grep -i "save\|cancel\|delete\|ok\|yes\|no" src/Locale/en.locale.xml | grep "" -A 1000 ``` **Reuse Framework labels when possible** to ensure consistency across the app. ### 4. Keep Label IDs Consistent Across Languages The `id` attribute MUST be identical in all language files: **✅ CORRECT:** ```xml ``` **❌ WRONG:** ```xml ``` ### 5. Document Context for Translators Add XML comments to provide context: ```xml ``` **Why:** Helps translators understand context and choose accurate translations. --- ## Common Issues and Solutions ### Issue 1: Label Shows ID Instead of Text **Symptom:** UI displays `CustomerNameLabelId` instead of "Customer Name" **Root Cause:** Label ID defined in UI contract but missing from locale file **Solution:** 1. Find the label ID in your UI contract: ```bash grep "CustomerNameLabelId" src/MyModule/PR/MyModule_Detail/*.xml ``` 2. Add to appropriate `` section in locale file: ```xml ``` 3. Rebuild and test: ```bash sf mdl build ``` ### Issue 2: Translation Not Appearing **Symptom:** English text shows even though German locale selected **Root Cause:** Label missing from `de.locale.xml` or has wrong `translationStatus` **Solution:** 1. Verify label exists in target language file: ```bash grep "CustomerNameLabelId" src/Locale/de.locale.xml ``` 2. If missing, add it: ```xml ``` 3. Verify `translationStatus` is `"7"` (translated), not `"1"` (untranslated) ### Issue 3: Build Error - UserInterface ID Missing **Error Message:** ``` Cannot find UserInterface section for id="MyModule_DetailUI" in locale file ``` **Root Cause:** UI contract references a locale section that doesn't exist **Solution:** Add the `` section to all locale files: ```xml ``` --- ## Summary **Key Takeaways:** 1. **Framework and Global = READ-ONLY** — Never modify these sections 2. **UserInterfaceContracts = CUSTOMER-EDITABLE** — Add your custom labels here 3. **One UserInterface section per UI contract** — Organize by UI file 4. **Keep label IDs consistent** — Same ID across all language files 5. **Meaningful defaultLabel values** — Provide useful fallback text 6. **Check Framework first** — Reuse existing labels when possible 7. **Test in all languages** — Verify translations display correctly 8. **New language = Copy en.locale.xml** — Translate only UserInterfaceContracts section **Quick Checklist:** - [ ] Label ID defined in UI contract with meaningful `defaultLabel` - [ ] `` section exists in locale files - [ ] Label added to UserInterfaceContracts in **all** language files - [ ] Label IDs are consistent across all language files - [ ] `translationStatus="7"` for translated labels - [ ] Framework/Global sections left untouched - [ ] Build succeeds without locale errors - [ ] Labels display correctly in simulator for all languages --- ## Related Documentation - [UI Control Dependencies](../patterns/ui-control-dependencies.md) - Label as binding target pattern - [Create UI Page](../skills/create-ui-page/SKILL.md) - UI structure with labels - [Build Error Quick Reference](../reference/build-error-quick-reference.md) - Error patterns