anyproto/localization-developer

Localization Developer (Smart Router)

Purpose

Context-aware routing to the Anytype iOS localization system. Helps you navigate the 3-file .xcstrings structure and use Loc constants correctly.

When Auto-Activated

• Working with .xcstrings files
• Using Loc constants
• Discussing hardcoded strings or user-facing text
• Keywords: localization, strings, text, Loc., .xcstrings

🚨 CRITICAL RULES (NEVER VIOLATE)

1. NEVER use hardcoded strings in UI - Always use Loc constants
2. NEVER create duplicate keys across the 3 .xcstrings files - Breaks code generation
3. NEVER edit non-English translations - Only update English (en), Crowdin handles others
4. ALWAYS search for existing keys first - Reuse before creating new
5. ALWAYS run make generate after editing .xcstrings files

📋 Quick Workflow

1. Search existing: rg "yourSearchTerm" Modules/Loc/Sources/Loc/Generated/Strings.swift
2. If found: Reuse existing key
3. If not found: Add to appropriate .xcstrings file (see decision tree below)
4. Generate: make generate
5. Use: AnytypeText(Loc.yourKey, style: .uxCalloutMedium)

🗂️ The 3-File System

Decision Tree

Is this text for authentication/login/vault?
    YES → Auth.xcstrings (86 keys)
    NO  → Continue

Is this text for spaces/objects/collaboration?
    YES → Workspace.xcstrings (493 keys)
    NO  → Continue

Is this text for settings/widgets/general UI?
    YES → UI.xcstrings (667 keys)

File Locations

• Auth.xcstrings: Modules/Loc/Sources/Loc/Resources/Auth.xcstrings
• Workspace.xcstrings: Modules/Loc/Sources/Loc/Resources/Workspace.xcstrings
• UI.xcstrings: Modules/Loc/Sources/Loc/Resources/UI.xcstrings

Generated output: All 3 files → single Strings.swift (~5,000 lines, 1,246 total keys)

🎯 Adding Keys

Format (add to appropriate .xcstrings file)

"Your localization key" : {
  "extractionState" : "manual",
  "localizations" : {
    "en" : {
      "stringUnit" : {
        "state" : "translated",
        "value" : "Your English text here"
      }
    }
  }
}

Key naming:

• Short keys: "No properties yet" ✅
• Not full sentences: "No properties yet. Add some." ❌
• Hierarchical: "QR.join.title" → Loc.Qr.Join.title

🔢 Dynamic Localization (Parameters)

✅ CORRECT - Use generated functions

// String: "You've reached the limit of %lld editors"
Loc.SpaceLimit.Editors.title(4)

// String: "Welcome, %@!"
Loc.welcomeMessage("John")

❌ WRONG - Never use String(format:)

String(format: Loc.limitReached, 10)  // DON'T DO THIS

Why: SwiftGen auto-generates parameterized functions for format specifiers (%lld, %d, %@).

Format specifiers:

• %lld → Int parameter
• %d → Int parameter
• %@ → String parameter
• %.1f → Double parameter

🗑️ Removing Unused Keys

1. Search: rg "keyName" --type swift
2. If only in Strings.swift: Key is orphaned
3. Remove from source .xcstrings file
4. Generate: make generate

⚠️ Common Mistakes

Hardcoded Strings

// ❌ WRONG
Text("Delete")

// ✅ CORRECT
Text(Loc.delete)

Duplicate Keys Across Files

// In Auth.xcstrings
"Settings" : { ... }

// In UI.xcstrings
"Settings" : { ... }  // ❌ DUPLICATE! Breaks generation

Using String(format:)

// ❌ WRONG
String(format: Loc.limitReached, 10)

// ✅ CORRECT
Loc.limitReached(10)

Editing Non-English

// ❌ WRONG - Crowdin will overwrite
"de" : { "value" : "Meine Übersetzung" }

// ✅ CORRECT - Only edit English
"en" : { "value" : "My translation" }

📚 Complete Documentation

Full Guide: Anytype/Sources/PresentationLayer/Common/LOCALIZATION_GUIDE.md

For comprehensive coverage of:

• Detailed 3-file system explanation
• Key naming patterns and conventions
• Dynamic localization with all format specifiers
• Translation workflow with Crowdin
• Removing orphaned keys
• Generated file structure
• Complete examples and troubleshooting

✅ Workflow Checklist

• [ ] Searched for existing keys (rg in Strings.swift)
• [ ] Added to correct .xcstrings file (Auth/Workspace/UI)
• [ ] No duplicate keys across files
• [ ] Only updated English (en)
• [ ] Ran make generate
• [ ] Used generated key: Loc.yourKey
• [ ] No hardcoded strings in UI

🔗 Related Skills & Docs

• ios-dev-guidelines → IOS_DEVELOPMENT_GUIDE.md - Never use hardcoded strings
• code-generation-developer → CODE_GENERATION_GUIDE.md - Understanding make generate
• design-system-developer → Using Loc constants in UI components

---

Navigation: This is a smart router. For deep details, always refer to LOCALIZATION_GUIDE.md.