Internationalization in Summon

This document provides an overview of Summon's internationalization (i18n) capabilities, including how to set up multiple languages, handle RTL languages, and integrate translations into your application.

Table of Contents

1. Overview
2. Setting Up Languages
3. Creating Translation Files
4. Using Translations
5. RTL Support
6. Directional Modifiers
7. Switching Languages
8. Best Practices

Overview

Summon provides a complete internationalization solution that allows you to:

• Support multiple languages in your application
• Handle right-to-left (RTL) languages like Arabic and Hebrew
• Define translations in simple JSON files
• Use composable functions to access translations
• Automatically adjust layout based on text direction

Setting Up Languages

To configure the languages your application supports, use the I18nConfig object:

// In your application initialization
fun main() {
    // Configure languages
    I18nConfig.configure {
        language("en", "English")
        language("fr", "Français")
        language("ar", "العربية", LayoutDirection.RTL)
        language("he", "עברית", LayoutDirection.RTL)
        
        // Set the default language
        setDefault("en")
    }
    
    // Load translations (platform-specific)
    // ...
}

Language Configuration Options

Each language is defined with:

• code: ISO language code (e.g., "en", "fr")
• name: Display name of the language
• direction: Text direction (defaults to LTR)

Creating Translation Files

Create JSON files for each supported language:

src/jsMain/resources/i18n/
  en.json
  fr.json
  ar.json
  he.json

Example translation file (en.json):

{
  "common": {
    "welcome": "Welcome to our application",
    "language": "Language",
    "back": "Back",
    "next": "Next",
    "save": "Save",
    "cancel": "Cancel"
  },
  "nav": {
    "home": "Home",
    "about": "About",
    "contact": "Contact"
  }
}

The same keys should be present in all language files, with translated values.

Using Translations

Loading Translations

JavaScript/Browser:

// JS-specific loading
JsI18nImplementation.init()
JsI18nImplementation.loadLanguageResources("/i18n/")

Accessing Translations

Use the stringResource composable function to get translated strings:

@Composable
fun WelcomeScreen() {
    Text(
        text = stringResource("common.welcome"),
        modifier = Modifier.padding("20px")
    )
    
    Button(onClick = { /* ... */ }) {
        Text(stringResource("common.next"))
    }
}

RTL Support

Summon supports right-to-left (RTL) languages with automatic layout adjustments.

Setting Up RTL Support

RTL support is automatically enabled when you define a language with LayoutDirection.RTL.

For JavaScript/browser applications, the dir attribute is automatically applied to the HTML element when the language changes.

Directional Modifiers

Use directional modifiers to create layouts that adapt to text direction:

@Composable
fun DirectionalExample() {
    Row(Modifier.directionalRow()) {
        // This row will automatically reverse in RTL mode
        Icon(imageVector = Icons.Default.ArrowForward)
        Text(
            text = stringResource("nav.next"),
            modifier = Modifier
                .paddingStart("8px")  // Will be left padding in LTR, right in RTL
                .paddingEnd("16px")   // Will be right padding in LTR, left in RTL
        )
    }
}

Available Directional Modifiers

• paddingStart(value): Padding on the starting edge
• paddingEnd(value): Padding on the ending edge
• marginStart(value): Margin on the starting edge
• marginEnd(value): Margin on the ending edge
• borderStart(width, style, color): Border on the starting edge
• borderEnd(width, style, color): Border on the ending edge
• directionalRow(): Row that reverses in RTL mode
• textStart(): Text aligned to the start edge
• textEnd(): Text aligned to the end edge
• withDirection(): Applies the dir attribute
• mirrorInRtl(): Mirrors the element in RTL mode

Switching Languages

To change the application language:

Button(onClick = { changeLanguage("ar") }) {
    Text("العربية")
}

The changeLanguage function will update the UI and document direction automatically.

Best Practices

1. Use directional modifiers instead of left/right-specific styles
2. Test with RTL languages early in development
3. Ensure all strings are translatable and avoid hardcoded text
4. Provide default values for missing translations
5. Consider text expansion when designing layouts
6. Mirror icons that indicate direction using mirrorInRtl() modifier
7. Use composable preview to test both LTR and RTL layouts

Advanced Topics

• Pluralization: For more complex translation requirements with plurals
• Date and number formatting: Using locale-specific formats
• Font considerations: Some languages may require different fonts or font sizes

For any questions or issues, please file a report in the issue tracker.