Localization & Display Formatting
Relevant source files
The following files were used as context for generating this wiki page:
- .agent/rules/localization.md
- Packages/Services/Tests/ServicesTests/Formatters/MoneyFormatterTests.swift
- Features/ExpensesFeature/Sources/ExpensesFeature/Views/SubscriptionForm/SubscriptionFormViewModel.swift
- Features/ExpensesFeature/Sources/ExpensesFeature/Views/CurrencyList/CurrencyListViewModel.swift
- Packages/SharedUI/Tests/SharedUITests/MonthlySpendingBarChartViewModelTests.swift
- README.md
Localization and Display Formatting in Trackurr ensures a native iOS experience by adapting the interface to the user's language, currency, and regional formatting preferences. The system primarily handles the transformation of domain models (like subscriptions and spending) into human-readable strings while maintaining strict separation between pure business logic and UI presentation.
The project utilizes modern Apple technologies, specifically String Catalogs (Localizable.xcstrings), to manage multi-language support across different feature modules and shared packages. This architecture allows the app to support diverse regions, including automated screenshot generation and metadata management for different locales.
Sources: .agent/rules/localization.md, README.md:38-40
Architecture & Principles
The localization architecture follows a strict "Pure Domain" principle. Domain models remain agnostic of UI concerns, while extensions in the SharedUI package or specific feature modules provide the necessary localization logic.
Core Guidelines
- String Catalogs: Used for all user-facing strings across packages.
- Model Extensions: Domain models are extended via
<ModelName>+Localization.swiftfiles within theSharedUI/Localization/directory to provide localized labels. - Number & Date Formatting: The app respects system locales for decimal separators and date formats, particularly in financial data entry and display.
Sources: .agent/rules/localization.md, README.md:162-167
Data Flow for Display Formatting
The following diagram illustrates how raw domain data is processed through formatters before reaching the View layer.
Financial & Currency Formatting
Financial formatting is handled by a dedicated MoneyFormatter service, which supports multiple styles including currency codes and symbols. It accounts for locale-specific grouping and decimal separators.
Formatting Styles
| Style | Example (en_US) | Example (pl_PL) | Description |
|---|---|---|---|
.code | USD 9.99 | PLN 9,99 | Displays the ISO currency code next to the value. |
.symbol | $9.99 | 9,99 zł | Displays the currency symbol (e.g., $, €, zł) with the value. |
Sources: Packages/Services/Tests/ServicesTests/Formatters/MoneyFormatterTests.swift:14-34, Packages/SharedUI/Tests/SharedUITests/MonthlySpendingBarChartViewModelTests.swift:65-80
Decimal Parsing & Normalization
A critical component of the input system is the normalization of decimal separators. Since different regions use commas (,) or periods (.), the system normalizes all input to use periods for internal Decimal representation before storage.
static func parseAmount(_ string: String) -> Decimal? {
let normalized = string.replacingOccurrences(of: ",", with: ".")
return Decimal(string: normalized)
}
Currency Management & Exchange Rates
The CurrencyListViewModel manages the display of available currencies, providing localized names and symbols. It also handles the display of real-time exchange rates relative to the user's default currency.
Currency List Components
- Locale Currency: Identifies the currency of the user's current locale.
- Popular Currencies: A filtered list of common currencies (USD, EUR, GBP, etc.).
- Exchange Rate Formatting: Formats rates with up to 4 decimal places (e.g.,
1 EUR = 1.0852 USD).
View Model Integration
View models are responsible for applying formatting logic so that views remain simple. For example, the MonthlySpendingBarChartViewModel uses a MoneyFormatter to generate compact labels for chart axes and tooltips.
Example: Compact Amount Formatting
The chart view model rounds values to the nearest whole number and applies currency symbols to keep the UI clean.
- Input: 18.99 (USD) -> Output: $19
- Input: 199.99 (PLN) -> Output: zł200
Sources: Packages/SharedUI/Tests/SharedUITests/MonthlySpendingBarChartViewModelTests.swift:57-78
Summary of Formatting Tools
| Tool/Service | Primary Responsibility | File Reference |
|---|---|---|
MoneyFormatter | Formatting amounts with codes/symbols | MoneyFormatterTests.swift |
SubscriptionFormViewModel | Normalizing decimal input and localized output | SubscriptionFormViewModel.swift |
CurrencyListViewModel | Localized currency names and exchange rates | CurrencyListViewModel.swift |
String Catalogs | Managing translation keys for all UI text | Localizable.xcstrings |
Fastlane | Automation of localized App Store screenshots | README.md |
Localization & Display Formatting is a foundational pillar of Trackurr, enabling the app to feel native in various global markets by handling the complexities of financial notation and regional differences automatically.