summacristian/localizerkit

**LocalizerKit** is a Swift Package that provides the foundation to localize your apps built in Swift Playground.

🚀 Usage

First, import the package wherever you need it:

import LocalizerKit

🗝️ Creating the keyset for your strings

This package relies on an enum to define the keys used for localized strings. This improves autocomplete, avoids typos, and makes the code easier to maintain.

Your keyset should conform to LocalizedKeyProtocol, and also be RawRepresentable with String and Hashable.

enum LocalizedKey: String, LocalizedKeyProtocol {
    case welcome
    case goodbye
    // ...
}

🧠 Why use an enum for keys?

LocalizerKit ensures your keys are compiler-checked. If you reference a missing key, your code won’t compile — no more runtime crashes due to typos. Plus, the IDE autocompletes your keys automatically, making localization fast, safe, and efficient.

📝 Defining localized strings

To define the actual strings, create one struct per supported language, conforming to LocalizedLanguage. Each struct must:

Specify its SupportedLanguage (e.g. .en, .it)
Provide a dictionary mapping keys to strings

struct EnglishStrings: LocalizedLanguage {
    static let language: SupportedLanguage = .en
    static let strings: [LocalizedKey: String] = [
        .welcome: "Welcome",
        .goodbye: "Goodbye"
    ]
}

💡 Tip: While LocalizerKit supports different keysets per language, it’s highly recommended to use a shared one for consistency and easier maintenance.

🔌 Registering localizations

You must register each language’s struct so that Localizer knows where to look.

You can do this automatically using a SwiftUI view modifier:

WindowGroup {
    ContentView()
        .localized(in: [EnglishStrings.self, ItalianStrings.self, GermanStrings.self])
}

This modifier registers each language into LocalizerRegistry, using the language specified in each struct.

⚠️ If multiple structs register for the same language, the last one will overwrite the previous entry.

🧩 Manual registration (advanced use)

You can skip the view modifier and register manually. For example, in your init():

init() {
    let languages = [EnglishStrings.self, ItalianStrings.self, GermanStrings.self]

    for language in languages {
        LocalizerRegistry.register(language)
    }
}

🌍 Language resolution and overrides

By default, LocalizerKit uses the first language from Locale.preferredLanguages that is also registered in LocalizerRegistry.

You can override this behavior with LocalizerSettings:

@StateObject private var settings = LocalizerSettings()

Toggle("Override system language", isOn: $settings.overrideSystemLanguages)

Picker("Language", selection: $settings.selectedLanguage) {
    ForEach(Localizer.availableLanguages, id: \.self) { lang in
        Text("\(lang.flag) \(lang.displayName)").tag(lang)
    }
}

The Localizer struct exposes two variables you can tinker with:

.overrideSystemLanguages: a Bool that, when set true, makes Localizer ignore the system's Locale.preferredLanguages
.selectedLanguage: a SupportedLanguage value that defines the app's language when override is enabled

When Localizer.overrideSystemLanguages is true, all localization lookups will use .selectedLanguage instead of the system locale. This makes it easy to detach your app’s language from the device’s settings, ideal for providing an in-app language picker for example.

🖥️ Using localized strings in views

Once set up, retrieving a localized string is simple:

Text(Localizer.get(LocalizedKey.welcome))

💡 Cleaner syntax with extension

To avoid writing LocalizedKey. every time, add this helper:

extension Localizer {
    public static func get(
      _ key: LocalizedKey,
      in lang: SupportedLanguage = Localizer.currentLanguage
    ) -> String {
        return get(key as any LocalizedKeyProtocol, in: lang)
    }
}

Then use:

Text(Localizer.get(.welcome))

You can locally override the language in a specific Text:

Text(Localizer.get(.welcome, in: .fr))

🌍 Adding a new localization

To add support for a new language:

Create a struct for the new language (e.g. SpanishStrings), implementing LocalizedLanguage.
Add it to the .localized(in: [...]) modifier or manually register it.

Done! The app will now automatically use that language if it matches the user’s preferred locale.

🌐 Supported Languages

LocalizerKit currently includes out-of-the-box translations for 30 languages, and growing. You can register just the ones you need for your app, no need to rush all of them at launch.

Supported languages include: | | | | |--------|--------|--------| | 🇺🇸 English | 🇮🇹 Italian | 🇫🇷 French | | 🇩🇪 German | 🇪🇸 Spanish | 🇵🇹 Portuguese | | 🇳🇱 Dutch | 🇸🇪 Swedish | 🇩🇰 Danish | | 🇫🇮 Finnish | 🇵🇱 Polish | 🇨🇿 Czech | | 🇷🇴 Romanian | 🇭🇺 Hungarian | 🇬🇷 Greek | | 🇹🇷 Turkish | 🇷🇺 Russian | 🇺🇦 Ukrainian | | 🇮🇱 Hebrew | 🇸🇦 Arabic | 🇮🇳 Hindi | | 🇨🇳 Chinese | 🇯🇵 Japanese | 🇰🇷 Korean | | 🇻🇳 Vietnamese | 🇹🇭 Thai | 🇮🇩 Indonesian | | 🇲🇾 Malay | 🇳🇴 Norwegian | 🇮🇷 Persian |

📦 Installation

To use LocalizerKit in your project:

Open Swift Playground or Xcode.
Add a Swift Package dependency with this URL:

https://github.com/SummaCristian/LocalizerKit.git

Import the module in your files:

import LocalizerKit

📄 License

LocalizerKit is released under the MIT License. See the LICENSE file for more details.

Package Metadata

Repository: summacristian/localizerkit

Default branch: main

README: README.md