Localization
Relevant source files
The following files were used as context for generating this wiki page:
Localization in the putio-ios project ensures that user-facing copy, including navigation elements, error messages, and dynamic content, is manageable and translatable. Currently, the application uses English as its base locale, with strings extracted into .strings files.
The localization system is primarily focused on two areas: UI element titles (such as navigation buttons and menus) and the API Error Localizer, which maps technical SDK errors to user-friendly, localized recovery suggestions.
Sources: CONTRIBUTING.md:79-84, Putio/Common/API/PutioSDK+ErrorLocalizer.swift:1-5
UI and Navigation Localization
User-facing copy in Swift code is wrapped in NSLocalizedString. This applies to static titles in view controllers, context menu actions, and settings section headers.
Navigation and Action Items
View controllers dynamically configure their navigation items and toolbars using localized strings. For instance, the FilesViewController adjusts toolbar button titles based on whether the "Trash" feature is enabled in user settings.
| Element | Localized Keys (Examples) | Context |
|---|---|---|
| File Actions | "Select", "New Folder", "Name", "Ascending" | Navigation bar menu |
| Toolbar | "Move", "Trash", "Delete" | Bulk editing mode |
| Contextual Actions | "Revoke" | Auth Apps table view |
Sources: PutioTests/NavigationLocalizationTests.swift:6-45, Putio/Features/Settings/SettingsViewModel+Sections.swift:15-180
Localization Workflow
Developers are required to maintain the following files when changing user-facing copy:
- Swift Code: Update
Putio/en.lproj/Localizable.strings. - Interface Builder: Update the matching
.stringsfile for the specific Storyboard or XIB inPutio/en.lproj/. - Validation: Use
plutil -lint Putio/en.lproj/*.stringsto verify file integrity.
Sources: CONTRIBUTING.md:79-83, CLAUDE.md:65-68
API Error Localization
The project implements a structured error localization system that transforms PutioSDKError types into PutioLocalizedError objects. This system provides both a human-readable message and a "recovery suggestion," which can be a simple instruction or a triggerable action.
Error Localizer Components
| Component | Description |
|---|---|
APIErrorLocalizer | A struct that matches errors (by status code or error type) and returns a PutioLocalizedError. |
PutioLocalizedError | Contains the localized message, a recoverySuggestion, and the underlyingError. |
PutioLocalizedErrorRecoverySuggestion | Enum defining either an .instruction(description:) or an .action(description:trigger:). |
Sources: Putio/Common/API/PutioSDK+ErrorLocalizer.swift:5-52
Localizer Logic Flow
The PutioSDK extension for error localization uses a matcher system to determine the appropriate localized response.
The flow prioritizes specific status code matches before falling back to error type matches or generic failure messages.
Sources: Putio/Common/API/PutioSDK+ErrorLocalizer.swift:85-115
Specific Implementation: Auth Errors
Authentication-specific localizations are handled in AuthErrors.swift, providing custom copy for login failures and two-factor authentication issues.
- Status Code 401: Mapped to "Invalid username or password".
- Error Type "invalid_code": Mapped to "The code you entered is invalid".
Sources: Putio/Features/Auth/AuthErrors.swift:5-40
Dynamic Content Localization
Certain parts of the app localize dynamic strings at runtime, such as storage usage or recovery placeholders in the database.
Realm Data Recovery
When the app recovers download records from UserDefaults, it assigns temporary localized placeholder names while waiting for API enrichment.
- Placeholder: "Recovering..."
- Formatters: "Video %d" and "Audio %d" are used if API enrichment fails.
Sources: Putio/Common/Helpers/Realm.swift:293-310
Settings and Formatting
Dynamic labels in settings use String(format:) with localized strings to display data-driven information.
- Storage: Uses format strings like
"%@ free of %@"or"%@ of %@ used". - Versions: Displays build numbers within the "About" section via
Bundle.main.versionNumber.
Sources: Putio/Features/Settings/SettingsViewModel+Sections.swift:154-159, Putio/Features/Settings/SettingsViewModel+Sections.swift:182-198
Summary
Localization in putio-ios is integrated into the architecture through standard NSLocalizedString calls and a specialized APIErrorLocalizer system. While currently focused on English coverage, the extraction of strings and the structured handling of errors provide a foundation for future multi-language support. Key hotspots for localization include navigation items in FilesViewController, settings categories in SettingsViewModel, and the error mapping logic in PutioSDK+ErrorLocalizer.