coenttb/swift-translating

A Swift package for inline translations.

Overview

swift-translating provides internationalization and localization for Swift applications with support for 180+ languages, automatic linguistic fallbacks, and integration with Swift Dependencies. The package includes components for translated strings, date formatting, singular/plural forms, and generic translated value containers.

Features

180+ language support with ISO 639-1/639-2 codes and locale mapping
Intelligent fallback chains based on linguistic and geographical relationships
Type-safe translation API with compile-time guarantees
Dictionary literal, parameter-based, and closure-based initialization patterns
Integration with Swift Dependencies for automatic language resolution
Localized date and time formatting across all languages
Singular/plural form handling for grammatical number variations
String concatenation and manipulation with translation preservation
Generic Translated<A> container supporting any type
Modular architecture allowing selective component import
Performance optimizations including lazy evaluation and caching

Installation

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/coenttb/swift-translating.git", from: "0.0.1")
]

Quick Start

import Translating
import Dependencies

// Create translated content
let greeting: TranslatedString = [
    .english: "Hello",
    .dutch: "Hallo",
    .french: "Bonjour"
]

// Use with dependency injection
withDependencies {
    $0.language = .dutch
} operation: {
    print(greeting.description) // "Hallo"
}

// Direct language access
let englishGreeting = greeting[.english] // "Hello"
let koreanGreeting = greeting[.korean]   // "Hello" (fallback)

Usage Examples

Translation Creation

Dictionary literal syntax (recommended for performance):

let welcome: TranslatedString = [
    .english: "Welcome",
    .dutch: "Welkom",
    .french: "Bienvenue",
    .spanish: "Bienvenido"
]

Parameter-based initialization:

let notification = TranslatedString(
    "New message",              // Default value
    dutch: "Nieuw bericht",
    french: "Nouveau message",
    german: "Neue Nachricht"
)

String literal for simple cases:

let message: TranslatedString = "Hello World"

Language Fallback System

Automatic fallbacks follow linguistic relationships:

let text: TranslatedString = [
    .english: "Hello",
    .dutch: "Hallo"
]

print(text[.afrikaans])    // "Hallo" (afrikaans → dutch → english)
print(text[.limburgish])   // "Hallo" (limburgish → dutch → english)
print(text[.chinese])      // "Hello" (chinese → english)

Each language has a predefined fallback chain. For example:

Afrikaans → Dutch → English → default
Basque → Spanish → French → English → default
Finnish → Swedish → English → default

Dependency Injection

Integration with Swift Dependencies for automatic language resolution:

import Dependencies

@Dependency(\.language) var currentLanguage

withDependencies {
    $0.language = .french
} operation: {
    // All TranslatedString.description calls use French
    print(greeting.description) // Uses French translation
}

Singular/Plural Forms

Handle grammatical number variations:

import SinglePlural

let itemLabel = SinglePlural(
    single: TranslatedString([.english: "item", .dutch: "item"]),
    plural: TranslatedString([.english: "items", .dutch: "items"])
)

let singleMessage = itemLabel(.single)  // Returns TranslatedString for "item"
let pluralMessage = itemLabel(.plural)  // Returns TranslatedString for "items"

Localized Date Formatting

Automatic date formatting for all languages:

import DateFormattedLocalized

let date = Date()
let formatted = date.formatted(
    date: .complete,
    time: .shortened,
    translated: true
)
// Creates TranslatedString with localized formats for all languages

Generic Translation Container

Translated<A> works with any type:

let prices: Translated<Double> = [
    .english: 9.99,
    .dutch: 8.99,
    .french: 10.99
]

let dutchPrice = prices[.dutch]  // 8.99

let settings: Translated<Bool> = [
    .english: true,
    .dutch: false
]

String Operations

Translation-preserving string operations:

let greeting: TranslatedString = [.english: "hello", .dutch: "hallo"]
let capitalized = greeting.capitalized
// capitalized.english == "Hello"
// capitalized.dutch == "Hallo"

let withPunctuation = greeting.period
// withPunctuation.english == "hello."
// withPunctuation.dutch == "hallo."

// Concatenation
let prefix: TranslatedString = [.english: "Good ", .dutch: "Goeie "]
let time: TranslatedString = [.english: "morning", .dutch: "morgen"]
let combined = prefix + time
// combined.english == "Good morning"
// combined.dutch == "Goeie morgen"

Module Architecture

The package is modular - import only what you need:

// Core language support
import Language                 // Language enum with 180+ codes

// Translation system
import Translated              // Generic Translated<A> container
import TranslatedString        // Specialized string translations

// Dependency injection
import Translating_Dependencies // Swift Dependencies integration

// Additional features
import SinglePlural            // Singular/plural form handling
import DateFormattedLocalized  // Localized date formatting

// All components
import Translating

Core Components

Language: Enum with 180+ ISO 639-1/639-2 language codes and locale conversion
Translated<A>: Generic container for translated values with intelligent fallback system
TranslatedString: Type alias for Translated<String> with additional string operations
SinglePlural<A>: Container for managing singular and plural forms
DateFormattedLocalized: Extension for creating localized date/time formatted strings

Performance Characteristics

Dictionary lookups: O(1) direct translation access
Lazy evaluation: Fallback chains computed only when needed
Memoization: Computed fallback results cached
Dictionary vs closure initialization: Dictionary literals are 4.5x faster

Performance recommendation:

// ✅ Preferred - Fast dictionary literal
let text: TranslatedString = [
    .english: "Hello",
    .dutch: "Hallo"
]

// ❌ Avoid - Closure called for every language in dependency
let text = TranslatedString { language in
    expensiveTranslationLookup(for: language)  // Called 180+ times
}

License

This package is licensed under the Apache License, Version 2.0. See LICENSE for details.

Contributing

Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.

Package Metadata

Repository: coenttb/swift-translating

Homepage: https://coenttb.com

Stars: 1

Forks: 0

Open issues: 2

Default branch: main

Primary language: swift

License: Apache-2.0

Topics: i18n, inline-translation, localization, multilingual, swift, translating, translation, web-development

README: README.md