0
# String Resources
1
2
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.
3
4
## Core Types
5
6
```kotlin { .api }
7
class StringResource(id: String, val key: String, items: Set<ResourceItem>) : Resource(id, items)
8
```
9
10
A string resource represents a localized text entry identified by a unique key. Each resource contains multiple variants for different locales and configurations.
11
12
## Composable Functions
13
14
### Basic String Loading
15
16
```kotlin { .api }
17
@Composable
18
fun stringResource(resource: StringResource): String
19
```
20
21
Loads a string resource within a Composable context. The function automatically uses the current environment to select the appropriate string variant.
22
23
**Usage:**
24
```kotlin
25
@Composable
26
fun WelcomeScreen() {
27
val title = stringResource(Res.string.welcome_title)
28
Text(text = title)
29
}
30
```
31
32
### Formatted String Loading
33
34
```kotlin { .api }
35
@Composable
36
fun stringResource(resource: StringResource, vararg formatArgs: Any): String
37
```
38
39
Loads a formatted string resource with variable arguments. Format placeholders in the string are replaced with the provided arguments.
40
41
**Parameters:**
42
- `resource` - The string resource containing format placeholders
43
- `formatArgs` - Variable arguments to substitute into the string
44
45
**Usage:**
46
```kotlin
47
@Composable
48
fun UserGreeting(userName: String, messageCount: Int) {
49
val greeting = stringResource(
50
Res.string.user_greeting,
51
userName,
52
messageCount
53
)
54
Text(text = greeting)
55
}
56
```
57
58
**String Resource Example:**
59
```xml
60
<string name="user_greeting">Hello %1$s, you have %2$d new messages</string>
61
```
62
63
## Suspend Functions
64
65
### Basic Non-Composable Loading
66
67
```kotlin { .api }
68
suspend fun getString(resource: StringResource): String
69
```
70
71
Loads a string resource outside of a Composable context using the system's resource environment.
72
73
**Usage:**
74
```kotlin
75
suspend fun loadWelcomeMessage(): String {
76
return getString(Res.string.welcome_message)
77
}
78
```
79
80
### Formatted Non-Composable Loading
81
82
```kotlin { .api }
83
suspend fun getString(resource: StringResource, vararg formatArgs: Any): String
84
```
85
86
Loads a formatted string resource outside of a Composable context.
87
88
**Usage:**
89
```kotlin
90
suspend fun createNotification(userName: String, count: Int): String {
91
return getString(Res.string.notification_message, userName, count)
92
}
93
```
94
95
### Environment-Specific Loading
96
97
```kotlin { .api }
98
suspend fun getString(environment: ResourceEnvironment, resource: StringResource): String
99
100
suspend fun getString(
101
environment: ResourceEnvironment,
102
resource: StringResource,
103
vararg formatArgs: Any
104
): String
105
```
106
107
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.
108
109
**Parameters:**
110
- `environment` - The resource environment specifying locale, theme, and density
111
- `resource` - The string resource to load
112
- `formatArgs` - Optional formatting arguments
113
114
**Usage:**
115
```kotlin
116
suspend fun getLocalizedString(locale: Locale): String {
117
val environment = ResourceEnvironment(
118
LanguageQualifier(locale.language),
119
RegionQualifier(locale.country),
120
ThemeQualifier.LIGHT,
121
DensityQualifier.MDPI
122
)
123
return getString(environment, Res.string.localized_content)
124
}
125
```
126
127
## String Formatting
128
129
The library supports standard string formatting patterns:
130
131
- **Positional arguments**: `%1$s`, `%2$d`, `%3$f`
132
- **Named arguments**: Arguments are replaced in order of appearance
133
- **Type safety**: Arguments are converted to strings automatically
134
135
**Format Specifiers:**
136
- `%s` - String
137
- `%d` - Integer
138
- `%f` - Float
139
- `%1$s` - First argument as string
140
- `%2$d` - Second argument as integer
141
142
## Localization
143
144
String resources support full localization through resource qualifiers:
145
146
**Directory Structure:**
147
```
148
res/
149
├── values/strings.xml # Default (English)
150
├── values-es/strings.xml # Spanish
151
├── values-fr/strings.xml # French
152
├── values-zh-rCN/strings.xml # Chinese (China)
153
└── values-ar/strings.xml # Arabic
154
```
155
156
**Automatic Selection:**
157
The library automatically selects the best matching string resource based on:
158
1. Exact locale match (language + region)
159
2. Language match (ignoring region)
160
3. Default fallback
161
162
## Error Handling
163
164
```kotlin { .api }
165
// Throws IllegalArgumentException if resource ID is not found
166
val text = stringResource(Res.string.missing_resource)
167
```
168
169
**Common Exceptions:**
170
- `IllegalArgumentException` - Resource ID not found in any resource file
171
- `MissingResourceException` - Resource file cannot be read
172
173
## Best Practices
174
175
1. **Use descriptive resource names**:
176
```kotlin
177
Res.string.user_profile_title // Good
178
Res.string.text1 // Bad
179
```
180
181
2. **Provide meaningful default text**:
182
```xml
183
<string name="loading_message">Loading content...</string>
184
```
185
186
3. **Use format arguments for dynamic content**:
187
```kotlin
188
stringResource(Res.string.items_count, itemCount)
189
```
190
191
4. **Always provide default (English) strings**:
192
Every string resource should have a default variant in `values/strings.xml`
193
194
5. **Handle pluralization with PluralStringResource**:
195
For quantity-dependent strings, use plural string resources instead of conditional logic.