You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: android-sdk/about.mdx
+7-8Lines changed: 7 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,11 +16,11 @@ For managing static translations in your repository, consider using the [Tolgee
16
16
17
17
## Overview
18
18
19
-
Tolgee Android SDK for **Android** and **Compose Multiplatform** lets you localize Kotlin-based applications with **dynamic content delivery**, adapting content to user behavior, preferences, and device data.
19
+
Tolgee Android SDK for **Android** and **Compose Multiplatform** lets you you update strings, without needing to publish new app versions or fixes.
20
20
21
21
**Supports Over‑the‑Air (OTA)** translation updates, providing translations dynamically **without needing to publish new app versions**.
22
22
23
-
The platform works offline with **caching**, **fallbacks**, **device-aware resource selection**, and **preloading** of critical namespaces for a smooth user experience. Tolgee **keeps UX consistent** by updating the UI automatically in response to locale changes, resulting in **fewer untranslated or mismatched strings**.
23
+
The platform works offline with **caching**, **fallbacks**, **device-aware resource selection**, and **preloading**. Tolgee **keeps UX consistent** by updating the UI automatically in response to locale changes, resulting in **fewer untranslated or mismatched strings**.
24
24
25
25
:::info
26
26
Tolgee gives you multiple hosting options: Cloud CDN (Cloud or self‑hosting) or your own CDN.
@@ -48,17 +48,16 @@ Tolgee Android SDK is split into modules so you only add what you need.
48
48
-**Core**
49
49
50
50
-**Over-the-air updates**: Update your translations without releasing a new app version.
Copy file name to clipboardExpand all lines: android-sdk/core-module/quickstart.mdx
+10-17Lines changed: 10 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,32 +24,27 @@ For managing static translations, we recommend using [Tolgee CLI](https://github
24
24
25
25
# Quickstart
26
26
27
-
This guide shows you how to integrate Tolgee Android SDK using the **Core module** for traditional Android Views.
28
-
29
-
The **Core module** is a Kotlin Multiplatform library that provides runtime support for Tolgee translations in your app. With Tolgee, you can update your translations **over-the-air** without releasing a new app version.
30
-
27
+
This guide shows you how to integrate Tolgee Android SDK using the **Core module** for traditional Android Views. The **Core module** is a library that provides runtime support for Tolgee translations in your app.
31
28
:::info
32
29
Using **Version Catalog** is recommended to keep your versions aligned, especially in bigger projects. This provides **readability, centralization, and consistency**.
33
30
:::
34
31
35
32
:::note
36
-
To build configuration examples use Kotlin DSL (build.gradle.kts). Groovy DSL may work but is not officially supported/tested.
33
+
Configuration exaples below are written in Kotlin DSL. Groovy DSL should work but is not officially supported/tested.
37
34
:::
38
35
39
36
1. Add dependency (Core):
40
37
41
-
In `gradle/libs.versions.toml`<u>add an alias for Tolgee library</u>.
38
+
In `gradle/libs.versions.toml`**add an alias for Tolgee library**.
42
39
43
40
```toml
44
-
# gradle/libs.versions.toml
45
41
[libraries]
46
42
tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "core", version.ref = "tolgee" }
47
43
```
48
44
49
-
Then, in `build.gradle.kts`, <u>use the created alias</u>.
45
+
Then, in `build.gradle.kts`, **use the created alias**.
50
46
51
47
```kotlin
52
-
// build.gradle.kts (module)
53
48
dependencies {
54
49
implementation(libs.tolgee)
55
50
}
@@ -58,7 +53,6 @@ dependencies {
58
53
For **smaller projects** you can also add dependency directly (the old way).
@@ -85,7 +78,11 @@ Could not find io.tolgee.mobile-kotlin-sdk:core
85
78
86
79
verify that Maven Central is included in your repository configuration.
87
80
88
-
3. Allow CDN networking (required when using Tolgee Cloud CDN):
81
+
3. Allow CDN networking:
82
+
83
+
:::info
84
+
Allowing `tolgee.io` and `tolg.ee` domains is required when using Tolgee Cloud CDN. If you access your own self-hosted CDN, here is where you should add the domain of your CDN.
85
+
:::
89
86
90
87
Create a network security config file `network_security.xml` in your `res/xml` folder:
91
88
@@ -107,10 +104,6 @@ Add network security config to your `AndroidManifest.xml`:
107
104
</application>
108
105
```
109
106
110
-
:::info
111
-
Allowing `tolgee.io` and `tolg.ee` domains is required when using Tolgee Cloud CDN. If you only access your own self-hosted CDN, include your domain(s) accordingly.
-listen for changes: `tolgee.changeFlow`; and respond to them: `tolgee.addChangeListener.
26
26
27
27
## Getting Translations
28
28
29
-
### 1. One time translations:
29
+
### One time translations:
30
30
31
31
```kotlin
32
32
val text:String?= tolgee.t("key")
33
33
```
34
34
35
-
Returns null if isn’t loaded yet (e.g.,SDK hasn't downloaded data)
35
+
Returns null if translations are not yet loaded (e.g.,SDK hasn't downloaded data).
36
36
37
-
Returns string when loaded.
37
+
Returns a string when translations are loaded.
38
38
39
39
**Use for simple/static text** (e. g., error messages, titles).
40
40
41
-
### Get a translation with fallback to Android resources
41
+
:::note
42
+
If you choose this function for your app, creating a **global corutine** with `Tolgee.preload()` is reccomended. See a tip under **A) Preload translations for the current locale from Activity** section.
43
+
:::
44
+
45
+
### Translation with parameters:
42
46
43
47
```kotlin
44
-
valtext = tolgee.t(context, R.string.string_key)
48
+
valtextWithParams:String?= tolgee.t("key_with_param", mapOf("param" to "value"))
45
49
```
46
50
47
-
:::info
48
-
Fallbacks provide a safety net in case of any problems with loading the translation or pulling from Android resources.
51
+
**_Use for translation with dynamic values._** Add data that changes during the app's runtime (e.g., dates, numbers, usernames).
52
+
53
+
:::note
54
+
To use parameters with Android fallbacks and ensure that translations from CDN can be interpreted, follow ICU order.
55
+
:::
56
+
57
+
:::note
58
+
If you choose this function for your app, creating a **global corutine** with `Tolgee.preload()` is reccomended. See a tip under **A) Preload translations for the current locale from Activity** section.
49
59
:::
50
60
51
-
###2. Translation with parameters:
61
+
#### a) Preload translations for the current locale
52
62
53
63
```kotlin
54
-
val textWithParams:String?= tolgee.t("key_with_param", mapOf("param" to "value"))
64
+
overridefunonStart() {
65
+
super.onStart()
66
+
tolgee.preload(this)
67
+
}
55
68
```
56
69
57
-
**_Use for translation with dynamic values._** Add data that changes during the app's runtime (e.g., dates, numbers, usernames).
70
+
Improves perceived performance - ensures strings are ready sooner for the current locale.
71
+
**Use for UI’s where the translations are critical (e.g., login, onboarding).**
58
72
59
73
:::tip
60
-
Android-style strings, placeholders follow Sprintf order (e.g., %1$s, %2$d).
74
+
**Create a global corutine by calling `Tolgee.preload()` function with both, mentioned, one-time translations and translations with parameters.
61
75
:::
62
76
63
-
### Get a translation with fallback to Android resources with parameters
77
+
#### b) Get a translation with fallback to Android resources
78
+
79
+
Fallbacks provide a safety net in case of any problems with loading the translation or pulling from Android resources.
80
+
81
+
**- One time translation with fallbacks:**
82
+
83
+
```kotlin
84
+
val text = tolgee.t(context, R.string.string_key)
85
+
```
86
+
87
+
**- Translation with parameters & fallbacks:**
64
88
65
89
```kotlin
66
90
val textWithParams = tolgee.t(context, R.string.string_with_params, "param1", "param2")
67
91
```
68
92
69
-
### Semi-dynamic updates for classic Views
93
+
#### c) Semi-dynamic updates for classic Views
70
94
71
95
:::info
72
96
To receive fresh translations without needing to publish new app versions follow these steps:
73
97
:::
74
98
75
-
a) Wrap your Activity context so Android resource lookups use Tolgee:
99
+
**- Wrap your Activity context so Android resource lookups use Tolgee:**
76
100
77
101
```kotlin
78
102
classMyActivity : Activity() {
@@ -82,7 +106,7 @@ class MyActivity : Activity() {
82
106
}
83
107
```
84
108
85
-
b) Trigger a UI refresh when locale/translations change:
109
+
**- Trigger a UI refresh when locale/translations change:**
86
110
87
111
```kotlin
88
112
lifecycleScope.launch {
@@ -92,9 +116,9 @@ lifecycleScope.launch {
92
116
}
93
117
```
94
118
95
-
Combining those two approaches gives **semi-dynamic behavior**: translations update after an Activity reload, not instantly. These methods can be used with ways mentioned above (**a one-time translation** and **translations with parameters**).
119
+
Combining those two approaches gives you **semi-dynamic behavior**: translations update after an Activity reload, not instantly. This setup works with both one-time translations and translations with parameters.
96
120
97
-
### 3. Get dynamic (reactive) translations.
121
+
### Get dynamic (reactive) translations.
98
122
99
123
```kotlin
100
124
val textFlow:Flow<String> = tolgee.tFlow("key")
@@ -105,11 +129,13 @@ textFlow.collect { text ->
105
129
106
130
**Use for reactive UI.** Translations update **immediately and automatically** whenever the language or CDN data changes.
107
131
108
-
###Get a reactive translation with fallback to Android resources
132
+
#### **- Reactive translation with fallback to Android resources**
109
133
134
+
```kotlin
110
135
val textFlow = tolgee.tFlow(context, R.string.string_key)
136
+
```
111
137
112
-
:::tip
138
+
:::note
113
139
In Compose, use `collectAsState()` function for a more idiomatic integration. See more in [**Jetpack Compose Usage**](./jetpack/usage.mdx).
114
140
:::
115
141
@@ -129,7 +155,6 @@ textView.text = itemsText
129
155
130
156
See also: [Android XML format](/platform/formats/android_xml) · [Tolgee Universal ICU placeholders](/platform/translation_process/tolgee_universal_icu_placeholders)
131
157
132
-
133
158
## Locale Management
134
159
135
160
### 1. Set the locale manually.
@@ -185,9 +210,10 @@ Tolgee.init {
185
210
}
186
211
```
187
212
188
-
**Use for easy scenarios**, when you are using classic formatters (`%s, %d, %1$s`).
213
+
**Use for easy scenarios**, when you are using classic formatters (`%s, %d, %1$s`).
214
+
**These parameters won't work with fallbacks to Android Resources** - it's not functional for apps with any offline activity.
189
215
190
-
2. ICU (advanced)
216
+
2. ICU (Native Flat JSON)
191
217
192
218
```kotlin
193
219
Tolgee.init {
@@ -198,32 +224,23 @@ Tolgee.init {
198
224
}
199
225
```
200
226
201
-
**Use for more advanced translations**, when you need formatters like (**few, may, female, complex lingual principles**).
202
-
203
-
## Preload translations for the current locale from Activity
204
-
205
-
```kotlin
206
-
overridefunonStart() {
207
-
super.onStart()
208
-
tolgee.preload(this)
209
-
}
210
-
```
211
-
212
-
Improves perceived performance and avoids empty/late.
213
-
**Use for UI’s where the translations are critical (e.g., login, onboarding).**
227
+
**Use for more advanced translations and ICU features**, when you need nested formats or formatters like e.g. few, may, female, complex lingual principles.
228
+
:::info
229
+
As mentioned in
214
230
215
231
## Example Projects
216
232
217
233
**For complete examples of how to use the Tolgee Core module**, check out the demo projects:
@@ -86,9 +82,13 @@ Could not find io.tolgee.mobile-kotlin-sdk:compose
86
82
87
83
verify that Maven Central is included in your repository configuration.
88
84
89
-
3. Allow CDN networking (required when using Tolgee Cloud CDN):
85
+
3. Allow CDN networking:
90
86
91
-
Create a network security config file `network_security.xml` in your `res/xml` folder:
87
+
:::info
88
+
Allowing `tolgee.io` and `tolg.ee` domains is required when using Tolgee Cloud CDN. If you access your own self-hosted CDN, here is where you should add the domain of your CDN.
89
+
:::
90
+
91
+
Create a network security config file `network_security.xml` in your `res/xml` folder:
0 commit comments