String Resources

String resources provide type-safe access to localized text content with formatting support. The library automatically selects the appropriate string variant based on the current locale and environment settings.

Core Types

class StringResource(id: String, val key: String, items: Set<ResourceItem>) : Resource(id, items)

A string resource represents a localized text entry identified by a unique key. Each resource contains multiple variants for different locales and configurations.

Composable Functions

Basic String Loading

@Composable
fun stringResource(resource: StringResource): String

Loads a string resource within a Composable context. The function automatically uses the current environment to select the appropriate string variant.

Usage:

@Composable
fun WelcomeScreen() {
    val title = stringResource(Res.string.welcome_title)
    Text(text = title)
}

Formatted String Loading

@Composable
fun stringResource(resource: StringResource, vararg formatArgs: Any): String

Loads a formatted string resource with variable arguments. Format placeholders in the string are replaced with the provided arguments.

Parameters:

• resource - The string resource containing format placeholders
• formatArgs - Variable arguments to substitute into the string

Usage:

@Composable
fun UserGreeting(userName: String, messageCount: Int) {
    val greeting = stringResource(
        Res.string.user_greeting,
        userName,
        messageCount
    )
    Text(text = greeting)
}

String Resource Example:

<string name="user_greeting">Hello %1$s, you have %2$d new messages</string>

Suspend Functions

Basic Non-Composable Loading

suspend fun getString(resource: StringResource): String

Loads a string resource outside of a Composable context using the system's resource environment.

Usage:

suspend fun loadWelcomeMessage(): String {
    return getString(Res.string.welcome_message)
}

Formatted Non-Composable Loading

suspend fun getString(resource: StringResource, vararg formatArgs: Any): String

Loads a formatted string resource outside of a Composable context.

Usage:

suspend fun createNotification(userName: String, count: Int): String {
    return getString(Res.string.notification_message, userName, count)
}

Environment-Specific Loading

suspend fun getString(environment: ResourceEnvironment, resource: StringResource): String

suspend fun getString(
    environment: ResourceEnvironment,
    resource: StringResource,
    vararg formatArgs: Any
): String

Loads string resources using a specific resource environment rather than the system default. This is useful for testing or when you need to load resources for a different locale/configuration.

Parameters:

• environment - The resource environment specifying locale, theme, and density
• resource - The string resource to load
• formatArgs - Optional formatting arguments

Usage:

suspend fun getLocalizedString(locale: Locale): String {
    val environment = ResourceEnvironment(
        LanguageQualifier(locale.language),
        RegionQualifier(locale.country),
        ThemeQualifier.LIGHT,
        DensityQualifier.MDPI
    )
    return getString(environment, Res.string.localized_content)
}

String Formatting

The library supports standard string formatting patterns:

• Positional arguments: %1$s, %2$d, %3$f
• Named arguments: Arguments are replaced in order of appearance
• Type safety: Arguments are converted to strings automatically

Format Specifiers:

• %s - String
• %d - Integer
• %f - Float
• %1$s - First argument as string
• %2$d - Second argument as integer

Localization

String resources support full localization through resource qualifiers:

Directory Structure:

res/
├── values/strings.xml              # Default (English)
├── values-es/strings.xml          # Spanish
├── values-fr/strings.xml          # French  
├── values-zh-rCN/strings.xml      # Chinese (China)
└── values-ar/strings.xml          # Arabic

Automatic Selection: The library automatically selects the best matching string resource based on:

1. Exact locale match (language + region)
2. Language match (ignoring region)
3. Default fallback

Error Handling

// Throws IllegalArgumentException if resource ID is not found
val text = stringResource(Res.string.missing_resource)

Common Exceptions:

• IllegalArgumentException - Resource ID not found in any resource file
• MissingResourceException - Resource file cannot be read

Best Practices

1. Use descriptive resource names:

   Res.string.user_profile_title // Good
   Res.string.text1             // Bad

2. Provide meaningful default text:

   <string name="loading_message">Loading content...</string>

3. Use format arguments for dynamic content:

   stringResource(Res.string.items_count, itemCount)

4. Always provide default (English) strings: Every string resource should have a default variant in values/strings.xml

5. Handle pluralization with PluralStringResource: For quantity-dependent strings, use plural string resources instead of conditional logic.