playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / localization

localization skill

/skills/ios/localization

This skill enforces iOS localization and asset standards to ensure complete localization and organized assets across projects.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill localization

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.9 KB
---
name: iOS Localization & Assets
description: Standards for String Catalogs, L10n, and Asset Management.
metadata:
  labels: [ios, localization, l10n, assets, xcassets]
  triggers:
    files: ['**/*.stringcatalog', '**/*.xcassets', '**/*.strings']
    keywords: [LocalizedStringResource, NSLocalizedString, String(localized:)]
---

# iOS Localization & Assets Standards

## **Priority: P1**

## Implementation Guidelines

### Localization (L10n)

- **String Catalogs (.stringcatalog)**: Use for primary localization in Xcode 15+. It provides a visual editor and compile-time checks for missing translations.
- **Native Implementation**: Use `String(localized: "key")` or `LocalizedStringResource`. Avoid manual `NSLocalizedString` where possible.
- **Pluralization**: Use String Catalogs' built-in pluralization support instead of complex code logic.
- **Formatting**: Use `Formatted` API for dates, numbers, and currencies to respect the user's locale.

### Asset Management

- **Asset Catalogs (.xcassets)**: Keep assets organized. Use folders with "Provides Namespace" enabled for large projects.
- **SF Symbols**: Use for standard icons to ensure consistency and accessibility.
- **Vector Assets**: Use PDF or SVG and enable "Preserve Vector Data" for resolution independence.

### Best Practices

- **Hardcoded Strings**: Never use hardcoded strings in UI. Every user-facing string must be localized.
- **Base Bundle**: Ensure `Base` localization is complete before adding other languages.

## Anti-Patterns

- **Manual String Formatting**: `**No manual currency symbol concat**: Use NumberFormatter or .formatted(.currency).`
- **Loose Asset Files**: `**No loose png/jpg files in repo**: Always use Asset Catalogs.`
- **Untranslated Keys**: `**No placeholder strings**: Ensure 100% coverage in String Catalogs.`

## References

- [L10n & Asset Organization](references/implementation.md)

Overview

This skill defines standards for iOS localization and asset management to ensure consistent, accessible, and maintainable apps. It covers String Catalogs, native localization APIs, pluralization, formatting, and asset catalog best practices. The goal is to eliminate hardcoded strings, prevent missing translations, and keep assets resolution-independent and organized.

How this skill works

The skill inspects localization workflows and asset organization, recommending Xcode 15+ String Catalogs and native APIs like String(localized:) or LocalizedStringResource. It enforces pluralization and formatting via the String Catalog and Formatted APIs, and audits asset placement to require .xcassets, namespace folders, SF Symbols usage, and vector preservation. It flags anti-patterns such as hardcoded UI strings, loose image files, manual currency concatenation, and untranslated placeholders.

When to use it

  • When starting a new iOS app or onboarding a new localization
  • Before adding new UI copy to ensure strings are cataloged
  • When preparing assets for multiple device resolutions and dynamic type
  • During code reviews or CI checks for localization coverage and asset hygiene
  • When enabling new languages or auditing existing translations

Best practices

  • Use String Catalogs (.stringcatalog) in Xcode 15+ as the single source of truth for translations
  • Prefer String(localized:) or LocalizedStringResource over manual NSLocalizedString
  • Rely on String Catalog pluralization and Formatted APIs for numbers, dates, and currencies
  • Organize images in .xcassets with 'Provides Namespace' folders for large projects
  • Use SF Symbols for common icons and vector PDFs/SVGs with 'Preserve Vector Data' enabled
  • Ensure Base localization is complete and avoid committing placeholder or missing keys

Example use cases

  • A CI job that fails the build if any String Catalog key is missing a translation
  • Migrating loose PNG/JPG files into a structured .xcassets catalog with namespaces
  • Replacing manual currency concatenation with .formatted(.currency) across app code
  • Standardizing iconography by switching to SF Symbols and updating design tokens
  • Auditing the app before a new language release to guarantee 100% string coverage

FAQ

Should I still use NSLocalizedString anywhere?

Prefer native String(localized:) or LocalizedStringResource; only use NSLocalizedString for legacy code that cannot be migrated immediately.

How do I handle pluralization for complex languages?

Use String Catalogs' built-in pluralization rules and provide language-specific variants rather than hand-rolled logic.