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
Tolgee Android SDK lets you localize Android apps with dynamic content delivery, Over‑the‑Air (OTA) translation updates, reactive locale changes, and seamless integration with Views and Jetpack Compose.
11
+
# Tolgee Android SDK
12
12
13
-
## Why use it
13
+
:::info
14
+
For managing static translations in your repository, consider using the [Tolgee CLI](/tolgee-cli/installation).
15
+
:::
14
16
15
-
-__Avoid releases for copy changes__: Ship translation fixes and new languages without a new app build.
16
-
-__Faster iteration__: Product/localization teams can push improvements instantly and validate in production.
17
-
-__Consistent UX__: UI updates reactively on locale change; fewer stale or mismatched strings.
18
-
-__Resilient by default__: Works offline with caching and resource fallbacks; fewer blank strings.
17
+
## Overview
19
18
20
-
## What you can do
19
+
Tolgee Android SDK lets you localize Android apps with dynamic content delivery, and lets you provide translations dynamically without needing to publish new app versions.
21
20
22
-
-__Over‑the‑Air (OTA) updates__: Deliver translations via CDN (Cloud or self‑host) with caching.
23
-
-__Views and Compose support__: `stringResource`/`pluralStringResource`, parameters, and reactive updates.
24
-
-__Runtime locale API__: Switch locales and react to `Tolgee.changeFlow`.
25
-
-__Fallbacks and preloading__: Android resources fallback; preload critical namespaces/locales.
26
-
-__Hosting options__: Tolgee Cloud CDN or your own CDN.
21
+
**Supports Over‑the‑Air (OTA)** translation updates, seamless integration with multiple systems, Android Views, Jetpack Compose and static translations.
22
+
23
+
## Why should you try it?
24
+
25
+
Tolgee platform lets you ship translations and new languages faster and easier without a new app build.
26
+
27
+
The platform works offline with caching, fallbacks to Android resources when needed, and preloading critical namespaces for a smooth user experience. Additionally, Tolgee keeps UX consistent by updating the UI automatically in response to translation or locale changes. These features result in fewer untranslated or mismatched strings of text.
28
+
29
+
## Features
30
+
31
+
### Over‑the‑Air (OTA) updates
32
+
33
+
Delivers translations via CDN (Cloud or self‑hosting) with caching and offline support.
34
+
35
+
### Change the app's language at runtime (Runtime locale API)
36
+
37
+
Use `tolgee.changeFlow` to monitor locale changes and update your UI accordingly.
38
+
39
+
### Works offline with fallbacks and preloading
40
+
41
+
Provides fallbacks to Android resources and preloading of critical namespaces.
42
+
43
+
### Support for Android Views, Jetpack Compose and static translations with CLI
44
+
45
+
Support for both coding functions `stringResource`, `pluralStringResource` and reactive updates.
46
+
47
+
### Hosting options
48
+
49
+
You have multiple hosting options: CDN (Cloud or self‑hosting).
Using **Version Catalog** is recommended to keep your versions aligned, especially in bigger projects. This provides **readability, centralization, and consistency**.
29
+
:::
30
+
16
31
1. Add dependency (Core):
17
32
18
-
Using Version Catalog is recommended to keep your versions aligned.
33
+
In `gradle/libs.versions.toml` <u>add an alias for Tolgee library</u>.
19
34
20
35
```toml
21
36
# gradle/libs.versions.toml
22
37
[libraries]
23
38
tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "core", version.ref = "tolgee" }
24
39
```
25
40
41
+
Then, in `build.gradle.kts`, <u>use the created alias</u>.
42
+
26
43
```kotlin
27
44
// build.gradle.kts (module)
28
45
dependencies {
29
46
implementation(libs.tolgee)
30
47
}
31
48
```
32
49
33
-
If you use Jetpack Compose, see the Compose variant: [Jetpack Installation](/android-sdk/jetpack/installation)
34
-
35
-
2. (If needed) Ensure repositories include Maven Central:
50
+
For **smaller projects** you can also add dependency directly (the old way).
To use the library, **you need to have proper repositories configured** in your project.
71
+
Otherwise an error like:
72
+
73
+
```text
74
+
Could not find io.tolgee.mobile-kotlin-sdk:core
75
+
```
76
+
might pop up.
77
+
Make sure **Maven Central** is set up properly so the dependency can be resolved.
78
+
43
79
3. Allow CDN networking (required when using Tolgee Cloud CDN):
44
80
45
81
Create a network security config file `network_security.xml` in your `res/xml` folder:
@@ -62,8 +98,9 @@ Add network security config to your `AndroidManifest.xml`:
62
98
</application>
63
99
```
64
100
65
-
> NOTE:
66
-
> 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.
101
+
:::note
102
+
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.
103
+
:::
67
104
68
105
## Initialization and configuration
69
106
@@ -83,19 +120,43 @@ class MyApplication : Application() {
83
120
}
84
121
```
85
122
86
-
How to get your CDN URL prefix (Content Delivery):
87
-
- Open Tolgee Platform → your Project → Developer settings → Content Delivery.
88
-
- Copy the full CDN URL prefix. You can use different prefixes per environment (dev/staging/prod).
89
-
- Optional: Verify connectivity locally:
123
+
When your app boots up, Tolgee is globally initialized. The translations are downloaded from CDN and cached locally. Other parts of your app (such as activities and fragments) can now use Tolgee without additional configuration.
124
+
125
+
***Make sure that your app knows where to download translations***:
126
+
127
+
For your app to download translation files, you need to provide a CDN URL prefix specific to your project. This prefix points to the catalog that contains your app’s translations.
128
+
129
+
### How to get your CDN URL prefix (Content Delivery):
130
+
1. Open Tolgee Platform → your Project → Developer settings → Content Delivery.
131
+
2. Copy the full CDN URL prefix.
132
+
3. You can use different prefixes per environment (dev/staging/prod).
You should receive a 200 response. If you get 403/404, double‑check the prefix.
140
+
You should receive a 200 response.
141
+
If you get 403 (Forbidden) or 404 (Not found), double‑check the prefix.
142
+
143
+
:::tip
144
+
Dynamic updates without republishing
145
+
:::
146
+
147
+
To receive fresh translations without needing to publish new app versions, wrap the base context in your Activities.
148
+
This way, APIs like getString() will use Tolgee dynamically.
149
+
150
+
- With wrapped context → fresh translations from the Tolgee CDN will be provided automatically.
151
+
152
+
- Without wrapped context → only the translations already bundled or previously cached will be available.
153
+
154
+
See the step-by-step guide in Usage.
155
+
156
+
:::note
157
+
If you have a different integration setup (for example, using tolgee-cli and bundling JSON translation files in assets), the initialization may look different.
158
+
:::
96
159
97
-
> TIP:
98
-
> For Activities, wrap the base context so `getString` and similar APIs use Tolgee. See step-by-step in [Usage](./usage.mdx).
0 commit comments